Return to TRIM Web Service Samples

There are potentially many situations where a developer using the TRIM Web Service will need to perform some operations on an object but will not know until runtime which specific object it is. Based on previous chapters, the only option would be to perform two executes on the Engine – one to identify the specific object, and a second to carry out the operations.

To cater for this situation, the concept of “injection” was developed. While there are several different types of Injection, the basic workings are the same – rather than pass a Uri into a parameter, you can pass a string value that the TRIM Web Service can resolve for a Uri. Injection works anywhere you would use a Uri.

Uri Injection is used in the situations where the Uri of the object is being found with some type of search, and then passed through to the next operation. Take, as an example, dealing with a RecordType Uri when creating a new Record. It is possible to do a search for the RecordType, have its Uri returned and then placed in a local variable before being passed into the Create object and sent off in a second execute.

Using Uri Injection means that these two executes can be grouped together – the search is carried out, and then the TRIM Web Service on the server side directly passes the result to the Create object using a FetchInjectionUri object.

The FetchInjectionUri object works a bit differently to a normal Fetch object. Instead of specifying what properties you want returned, you instead specify the FetchInjectionUri’s ID. This ID can be any string, but it needs to be unique for the Execute. The FetchInjectionUri object then caches the Uri found by the search for later use in the request.

By now you should be familiar with at least some of the objects in the TRIM Web Service that take a Uri as a parameter - for example specifying the RecordType when creating a new Record.

For Uri injection to work, you first need a successful search. We’ll assume for this example that you at least know the name of the RecordType you need. So you’ll need a search that can find the Record Type. As mentioned earlier, you can set the ID of the injection object to any string, but it needs to be unique for the request.

Example 1 – Creating a Record using Inject

Engine engine = new Engine();
engine.Credentials = System.Net.CredentialCache.DefaultCredentials;
 
RecordTypeStringSelect rts = new RecordTypeStringSelect();
rts.Arg = "Document";
rts.Id = "recordtype";
 
InputProperty name = new InputProperty();
name.Name = "recTitle";
name.Val = "New Record";
 
InputProperty type = new InputProperty();
type.Name = "recRecordType";
type.Val = "inject:recordtype";
 
Create create = new Create();
create.Items = new InputProperty[] {type, name};
create.TrimObjectType = "record";
 
FetchInjectionUri fiu = new FetchInjectionUri();
fiu.Id = "recordtype";
 
TrimRequest req = new TrimRequest();
req.Items = new Operation[] {rts, fiu, create};
TrimResponse resp = engine.Execute(req);

The first InputProperty is pretty standard – it’s just specifying the record title. The second InputProperty is what we’re really interested in. Notice that instead of specifying the Uri, we’ve instead set it to “inject:recordtype”. This is basically saying that this value will be set by the FetchInjectUri object.

As you’ve probably guessed, the reason the ID of the FetchInjectionUri object needs to be unique within a single request is that otherwise the TRIM Web Service doesn’t know which Uri to inject where. In fact if you reuse a FetchId, the old value will be silently overwritten with the new one.

Uri Injection replaces the need to search for an object and return its Uri before using the Uri in another request. Naturally, this is only useful when dealing with a single Uri. The operation will fail if the FetchInjectionUri has to deal with anything but a single Uri (so the search returns either nothing or more than one Uri). This prevents anything messy from happening if, for example creating a new record, your search returned two Record Types.

If you know the name of the object, you can use the “name:” injector. The “name:” injector saves the need to do a shortcut name or similar search. When the TRIM Web Service detects the “name:” syntax, it carries out a relevant name-based search automatically, by constructing the object using its name as you would in the TRIM SDK.

Example 2 – Creating a Record using Name

Engine engine = new Engine();
engine.Credentials = System.Net.CredentialCache.DefaultCredentials;
 
InputProperty name = new InputProperty();
name.Name = "recTitle";
name.Val = "New Record";
 
InputProperty type = new InputProperty();
type.Name = "recRecordType";
type.Val = "name:document";
 
Create create = new Create();
create.Items = new InputProperty[] {type, name};
create.TrimObjectType = "record";
 
TrimRequest req = new TrimRequest();
req.Items = new Operation[] {create};

Injectors are designed to help minimize executes and make life easier for the developer. There are many situations where using an injector will not be useful – or even possible. For example, a common mistake is trying to use an injector to pass an upload ID (see CheckIn and CheckOut) to a CheckIn object. This will not work, as the upload ID does not resolve to a Uri.