As part of the Relativity Services API (RSAPI) Deprecation, content on this page referring to the RSAPI and the Patient Tracker application is in the process of being deprecated and will no longer be supported. For more information and alternative APIs, see
RSAPI deprecation process.
Mass operations
The Services API provides you with the ability to perform an operation on multiple items with a single API call.
This page contains the following information:
See this related page:
Use Lists of Artifacts as input to CRUD methods
Each of the CRUD methods takes a List of Artifacts so you can perform these operations on multiple objects in single call. Use the following guidelines when submitting ArtifactRequests for CRUD operations:
- You can pass ArtifactRequests of different types. For example, you could submit a list of ArtifactRequests to the Update() method that contains Artifacts for Documents and Dynamic Objects.
- You must pass all the parameters required by the CRUD method that you are using for each ArtifactRequest. For example, you must pass the ArtifactType and list of Fields for each ArtifactRequest when creating Artifacts.
- No transactional guarantee exists for the method as a whole. The creation, update or deletion of each ArtifactRequest is handled individually. If the operation against a single ArtifactRequest fails, the Success flag on the Result object for the corresponding ArtifactRequest is set to False, and returned in the ResultSet. The operations on the other ArtifactRequests will proceed.
Mass create methods
You can use the MassCreate(), MassCreateWithDetails(), and MassCreateWithAPIParameters() methods to create multiple Dynamic Objects. The methods use a template to minimize the repetition of Field values that are common to all the Artifacts.
The MassCreateWithDetails() and MassCreateWithAPIParameters() methods also populate the Results property with success and failure information as part of the object creation process. This information is provided even when a partial failure occurs.
Additionally, MassCreateWithAPIParameters() can be used to link to single- or multi-object instances by ArtifactIDs. In order to do so, you must pass a comma-delimited list of corresponding Field ArtifactIDs.
The mass create methods take the Fields specified for each Artifact included in the List of Artifacts passed as a parameter.
View sample code for the MassCreate() method
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
public static bool Using_MassCreate(IRSAPIClient proxy)
{
// STEP 1: Create Artifact that serves as a template for the RDOs that you want to create.
ArtifactRequest artifactRequest = new ArtifactRequest("Employees");
List<Field> templateFields = new List<Field>();
templateFields.Add(new Field("Name"));
templateFields.Add(new Field("Last Name"));
templateFields.Add(new Field("Employment Level", 1036226));
artifactRequest.Fields = templateFields;
// STEP 2: Create a list of Artifacts of RDOs to create via MassCreate.
List<ArtifactRequest> artifactRequestList = new List<ArtifactRequest>();
for (int i = 1; i <= 10; i++)
{
ArtifactRequest anotherArtifactRequest = new ArtifactRequest();
List<Field> fields = new List<Field>();
fields.Add(new Field("Name", i.ToString()));
fields.Add(new Field("Last Name", "Employee #:" + i.ToString()));
anotherArtifactRequest.Fields = fields;
anotherArtifactRequest.ParentArtifactID = 1016204;
// The identifier 1016204 is the WorkspaceID.
artifactRequestList.Add(anotherArtifactRequest);
}
// STEP 3: Call the Services API to MassCreate the Employees.
MassCreateResult results = new MassCreateResult();
try
{
results = proxy.MassCreate(proxy.APIOptions, artifactRequest, artifactRequestList);
Console.WriteLine(string.Format("MassCreate Success Flag: {0}", results.Success));
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
if (!results.Success)
{
Console.WriteLine(results.Message);
foreach (Result r in results.Results)
{
Console.WriteLine(r.Message);
}
return false;
}
return true;
}
View sample code for the MassCreateWithDetails() method
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
public static bool Using_MassCreateWithDetails(IRSAPIClient proxy)
{
// STEP 1: Create Artifact that serves as a template for the RDOs that you want to create.
ArtifactRequest artifactRequest = new ArtifactRequest("Employees");
List<Field> templateFields = new List<Field>();
templateFields.Add(new Field("Name"));
templateFields.Add(new Field("Last Name"));
templateFields.Add(new Field("Employment Level", 1036226));
artifactRequest.Fields = templateFields;
// STEP 2: Create a list of Artifacts of the RDOs created via MassCreate.
List<ArtifactRequest> artifactRequestList = new List<ArtifactRequest>();
for (int i = 1; i <= 10; i++) {
ArtifactRequest anotherArtifactRequest = new ArtifactRequest();
List<Field> fields = new List<Field>();
fields.Add(new Field("Name", i.ToString()));
fields.Add(new Field("Last Name", "Employee #:" + i.ToString()));
anotherArtifactRequest.Fields = fields;
anotherArtifactRequest.ParentArtifactID = 1016204;
// The identifier 1016204 is the WorkspaceID.
artifactRequestList.Add(anotherArtifactRequest);
}
// STEP 3: Call the Services API to MassCreate the Employees.
MassCreateResult results = new MassCreateResult();
try {
results = proxy.MassCreateWithDetails(proxy.APIOptions, artifactRequest, artifactRequestList);
Console.WriteLine(string.Format("MassCreate Success Flag: {0}", results.Success));
}
catch (Exception ex) {
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
// The results objects contains the Artifact ID for each new Artifact.
if (results.Success) {
Console.WriteLine("Total Artifacts Created: " + results.Count);
foreach (Result result in results.Results)
{
Console.WriteLine("Created Artifact: " + result.ArtifactID);
}
}
else {
Console.WriteLine(results.Message);
foreach (Result r in results.Results) {
Console.WriteLine(r.Message);
}
return false;
}
//Clean up.
try {
artifactRequestList = new List<ArtifactRequest>();
for (int i = 1; i <= 10; i++) {
ArtifactRequest anotherArtifactRequest =
new ArtifactRequest("Employees", results.Results[i-1].ArtifactID);
artifactRequestList.Add(anotherArtifactRequest);
}
proxy.Delete(proxy.APIOptions, artifactRequestList);
}
catch (Exception ex) {
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
return true;
}
View sample code for the MassCreateWithAPIParameters() method
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
public static bool Using_MassCreateWithAPIParameters(IRSAPIClient proxy)
{
// STEP 1: Create Artifact that serves as a template for the RDOs that you want to create.
ArtifactRequest artifactRequest = new ArtifactRequest("Employees");
List<Field> templateFields = new List<Field>();
templateFields.Add(new Field("Name"));
templateFields.Add(new Field("Last Name"));
templateFields.Add(new Field("Employment Level", 1036226));
// Manager is a MultipleObject field that takes an Employee. In this example, all employees have
// a single, identical manager--the Employee with identifier 1037899.
FieldValueList<RDO> managers = new FieldValueList<RDO>();
managers.Add(new RDO(1037899));
Field manager = new Field("Manager", managers);
manager.FieldType = FieldType.MultipleObject;
// Office is a SingleObject field that takes a list of offices. In this example, all employees work
// in the same office--the Office with identifier 1037911.
Field office = new Field("Office", new RDO(1037911));
office.FieldType = FieldType.SingleObject;
templateFields.Add(manager);
templateFields.Add(office);
artifactRequest.Fields = templateFields;
// STEP 2: Create a list of Artifacts of the RDOs created via MassCreate.
List<ArtifactRequest> artifactRequestList = new List<ArtifactRequest>();
for (int i = 1; i <= 10; i++)
{
ArtifactRequest anotherArtifactRequest = new ArtifactRequest();
List<Field> fields = new List<Field>();
fields.Add(new Field("Name", i.ToString()));
fields.Add(new Field("Last Name", "Employee #:" + i.ToString()));
anotherArtifactRequest.Fields = fields;
anotherArtifactRequest.ParentArtifactID = 1016204;
// The identifier 1016204 is the WorkspaceID.
artifactRequestList.Add(anotherArtifactRequest);
}
// STEP 3: Create a comma-delimited string of the field identifiers for all single and multiple object fields.
List<string> fieldArtifactIdList = new List<string>();
foreach (Field field in templateFields)
{
if (field.FieldType == FieldType.MultipleObject || field.FieldType == FieldType.SingleObject)
{
fieldArtifactIdList.Add(field.ArtifactID.ToString());
}
}
string fieldArtifactIds = string.Join(",", fieldArtifactIdList);
//STEP 4: Create a list of API parameters for the MassCreate call.
List<APIParameters> apiParameterList = new List<APIParameters>();
APIParameters apiParameters = new APIParameters();
apiParameters.Key = kCura.Relativity.Client.Constants.APIParameterKeys.OBJECT_FIELDID_LIST_CONTAINS_ARTIFACTID;
apiParameters.Value = fieldArtifactIds;
apiParameterList.Add(apiParameters);
// STEP 4: Call the Services API to MassCreate the Employees.
MassCreateResult results = new MassCreateResult();
try
{
results = proxy.MassCreateWithAPIParameters(proxy.APIOptions, artifactRequest, artifactRequestList, apiParameterList);
Console.WriteLine(string.Format("MassCreate Success Flag: {0}", results.Success));
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
// The results objects contains the Artifact ID for each new Artifact.
if (results.Success)
{
Console.WriteLine("Total Artifacts Created: " + results.Count);
foreach (Result result in results.Results)
{
Console.WriteLine("Created Artifact: " + result.ArtifactID);
}
}
else
{
Console.WriteLine(results.Message);
foreach (Result r in results.Results)
{
Console.WriteLine(r.Message);
}
return false;
}
//Clean up.
try
{
artifactRequestList = new List<ArtifactRequest>();
for (int i = 1; i <= 10; i++)
{
ArtifactRequest anotherArtifactRequest =
new ArtifactRequest("Employees", results.Results[i - 1].ArtifactID);
artifactRequestList.Add(anotherArtifactRequest);
}
proxy.Delete(proxy.APIOptions, artifactRequestList);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
return true;
}
The mass create methods are subject to the following restrictions:
- Only Dynamic Objects can be created with this method.
- All Artifacts to be created must be of the same ArtifactType, and all Fields must be specified by Name. Don't use the ArtifactID.
- Each Field in the template must have a value, and be specified by Name. Don't use NULL values or specify Fields by ArtifactID.
- All required Fields must have values.
Note: The Instance setting table contains the MaxNumberOfArtfactsToMassCreate setting, which controls the maximum number of Dynamic Objects that can be create with this method. The default value is currently 1,000,000.
MassEdit() method
You can use the MassEdit() method to apply the same set of Field updates to multiple Documents in a single call. This method uses a template Document as an ArtifactRequest, which determines how the call updates other documents. It also takes a list of ArtifactIDs that identify the Documents for editing. You can only update Documents with this method, and updates aren't propagated to related documents as they are in the Relativity web UI.
Note: The Instance setting table contains the MaxNumberOfArtfactsToMassEdit setting, which controls maximum number of documents edited in a single call. The default value is 1,000,000. In addition, the MassEdit() method updates the documents in batches. MassEditBatchAmount is the configuration setting that controls the number of documents in each batch, and it is also used by the Relativity web UI. The default and recommended value is 1,000.
View sample code for the MassEdit() method
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
public static bool Using_MassEdit(IRSAPIClient proxy)
{
// STEP 1: Create Artifact that serves as a template for the Documents that you want to update.
List<Field> fields = new List<Field>();
fields.Add(new Field("MD5 Hash", "New Value"));
ArtifactRequest artifactRequest = new ArtifactRequest("Document");
artifactRequest.Fields = fields;
// STEP 2: Create a list of ArtifactIDs of the Documents updated via MassEdit.
List<Int32> artifactIDsToUpdate = new List<Int32>() {1035607, 1035608};
//STEP 3: Call the Services API to MassEdit the Documents.
MassEditResult resultSet;
try
{
resultSet = proxy.MassEdit(proxy.APIOptions, artifactRequest, artifactIDsToUpdate);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
Console.WriteLine(string.Format("MassEdit Success Flag: {0}", resultSet.Success));
// Check for success.
if (!resultSet.Success)
{
Console.WriteLine(resultSet.Message);
return false;
}
return true;
}
ExecuteBatch() method
You can use the ExecuteBatch() method to combine multiple operations in a single database transaction. For example, you could create a set of Artifacts and update a set of Documents using a single round-trip to the Services API.
View sample code for the ExecuteBatch() method
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
public static bool Using_ExecuteBatch(IRSAPIClient proxy)
{
// STEP 1: Create RDOs used later to demonstrate the ExecuteBatch() method.
ArtifactRequest artifactRequest1 = new ArtifactRequest();
artifactRequest1.ParentArtifactID = 1016204;
artifactRequest1.ArtifactTypeName = "Employees";
artifactRequest1.Fields = new List<Field>();
Field nameField1 = new Field("Name", "John");
Field lastNameField1 = new Field("Last Name", "Doe");
artifactRequest1.Fields.Add(nameField1);
artifactRequest1.Fields.Add(lastNameField1);
ArtifactRequest artifactRequest2 = new ArtifactRequest();
artifactRequest2.ParentArtifactID = 1016204;
artifactRequest2.ArtifactTypeName = "Employees";
artifactRequest2.Fields = new List<Field>();
Field nameField2 = new Field("Name", "Jane");
Field lastNameField2 = new Field("Last Name", "Smith");
artifactRequest2.Fields.Add(nameField2);
artifactRequest2.Fields.Add(lastNameField2);
List<ArtifactRequest> artifactRequestList = new List<ArtifactRequest>();
artifactRequestList.Add(artifactRequest1);
artifactRequestList.Add(artifactRequest2);
ResultSet results = new ResultSet();
// Attempt to create the new Users.
try
{
results = proxy.Create(proxy.APIOptions, artifactRequestList);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
List<ArtifactRequest> artifactRequestToReadList = new List<ArtifactRequest>();
foreach (Result result in results.Results)
{
ArtifactRequest artifactRequestToRead = new ArtifactRequest();
artifactRequestToRead.ArtifactID = result.ArtifactID;
artifactRequestToRead.ArtifactTypeID = 1000036;
artifactRequestToReadList.Add(artifactRequestToRead);
}
ReadResultSet readResultSet = new ReadResultSet();
//Read back the Users just created.
try
{
readResultSet = proxy.Read(proxy.APIOptions, artifactRequestToReadList);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
List<Artifact> sampleEmployees = new List<Artifact>();
foreach (ReadResult readResult in readResultSet.ReadResults)
{
sampleEmployees.Add(readResult.Artifact);
}
ArtifactRequest john =
new ArtifactRequest((Int32)sampleEmployees[0].ArtifactTypeID, (Int32)sampleEmployees[0].ArtifactID);
ArtifactRequest jane =
new ArtifactRequest((Int32)sampleEmployees[1].ArtifactTypeID, (Int32)sampleEmployees[1].ArtifactID);
// STEP 2: Create an Update Command for one artifact.
List<ArtifactRequest> artifactRequestsToUpdate = new List<ArtifactRequest> { john };
Field lastNameField = sampleEmployees[0].Fields.FirstOrDefault(field => field.Name == "Last Name");
lastNameField.Value = "Doe - Updated";
john.Fields.Add(lastNameField);
// Add a new skill to this employee by updating the Skills Inventory multichoice field.
Field skills = sampleEmployees[0].Fields.FirstOrDefault(field => field.Name == "Skills Inventory");
// Define the skill to be added as a MultiChoice Update Value that is 'merged' with any existing skill values.
MultiChoiceUpdateValue skillToBeAdded = new MultiChoiceUpdateValue();
skillToBeAdded.Value = new List<Int32>();
skillToBeAdded.Value.Add(1036219);
skillToBeAdded.Behavior = MultiChoiceUpdateBehavior.Merge;
// Set the Skills field value to be that of the MultiChoiceUpdateValue.
skills.Value = skillToBeAdded;
john.Fields.Add(skills);
Command anUpdateCommand = new UpdateCommand(artifactRequestsToUpdate);
//STEP 3: Create a Delete Command for an artifact.
List<ArtifactRequest> artifactRequestsToDelete = new List<ArtifactRequest>();
artifactRequestsToDelete.Add(jane);
Command aDeleteCommand = new DeleteCommand(artifactRequestsToDelete);
// STEP 4: Bundle the Command objects into a list. The commands are executed in the order that they are provided.
List<Command> commands = new List<Command>();
commands.Add(anUpdateCommand);
commands.Add(aDeleteCommand);
ExecuteBatchResultSet executeBatchResults = new ExecuteBatchResultSet();
// STEP 5: Call the Services API to execute the batch of Commands.
try
{
executeBatchResults = proxy.ExecuteBatch(proxy.APIOptions, commands, TransactionType.Batch);
Console.WriteLine(string.Format("Batch Success Flag: {0}", results.Success));
if (!results.Success)
{
foreach (ResultSet resultSetItem in executeBatchResults.ResultSets)
{
Console.WriteLine(resultSetItem.ResultSetType.ToString() + ": " + resultSetItem.Success.ToString());
foreach (Result resultItem in resultSetItem.Results)
{
if (!resultItem.Success)
Console.WriteLine(resultItem.Message);
}
}
return false;
}
}
catch (Exception ex)
{
Console.WriteLine("There was an error:" + ex.Message);
}
return true;
}
Use the following guidelines when calling this method:
- Input to the ExecuteBatch() method is a List of Command objects.
- All operations execute within a database transaction. If an error occurs, the entire batch is rolled-back.
- Executing a large number of create, update, and delete operations may take considerable time and result in table locking.
Note: The Instance setting table contains the MaxArtifactBatchSizeForExecuteBatch setting, which controls the number of Artifacts processed in a single method call. The default value is 2000, but you can update it as necessary. This setting has been implemented to limit the length of time that database transaction opened by ExecuteBatch() method holds locks on tables, preventing Relativity users from experiencing errors.
