Using the API to Automate Member Creation, Updates, and Deletions
What
I am a Digital.ai Agility administrator who would like to automate some of the tedious and error-prone administrative work. The most tedious task is provisioning users. What can we do to search/find existing users, create a new user when they don't already exist, modify a user account, and delete or deactivate a user.
How
The most important thing to understand is the general notion of users is known as Members in Digital.ai Agility. Before automating member management, you should be familiar with closely related concepts such as managing projects, default role, and project role.
The following uses the rest-1.v1/New and rest-1.v1/Data endpoints to work with user data. This recipe builds on creating a new asset, setting asset state, and updating an asset. If you have trouble with any of the individual steps, you may want to follow one of those more detailed recipes for deeper understanding.
Getting Started
- Have an HTTP Client.
- Obtain an API token.
- Explore the attributes for the asset type of
Member.
1. Find a Member
There are 2 mechanisms for checking if a Member already exists in the system. If your automation will have a user interface, then you may want to check for existing users by matching the names. If the automation will be entirely unattended, then you would need to establish unique key that works across systems. For example, you might key on Username which is required to be unique in Digital.ai Agility.
A. Find by Part of a Name
When we want a partial match, we can use the find parameter. To search for a substring in the Name attribute, we can send find and findin parameters to the rest-1.v1/Data endpoint. The following shows the HTTP GET request.
\<Server Base URI\>/rest-1.v1/Data/Member?sel=Name,Username,Email&find=Harrison&findin=Name
Because find is a substring search, the above would return results for "James Harrison" or "Harrison James".
B. Find by Email
When we want an exact match, we can use the where parameter. To search a full string in the Email attribute, we can send a where parameter to the rest-1.v1/Data endpoint. The following shows the HTTP GET request.
<Server Base URI>/rest-1.v1/Data/Member?sel=Name,Username,Email&where=Email='andre.agile@mailinator.com'
Because Email is not required to be unique, the result set may have multiple Member assets.
C. Find by Username
Like the prior example, we can match Username with an exact string. To search a full string in the Username attribute, we can send a where parameter to the rest-1.v1/Data endpoint. The following shows the HTTP GET request.
\<Server Base URI\>/rest-1.v1/Data/Member?sel=Name,Username,Email&where=Username='andre.agile'
Because Username is required to be unique, the result will have at most one Member asset.
2. Create a New Member
Create a new asset for a Member, named "Andre Agile". The rest-1.v1/New endpoint will provide a template with a default value for DefaultRole. We still need to provide the required fields (such as Name and IsCollaborator) and some non-required fields that are imminently useful for administration (such as Username and Email). The following is a representative XML payload that we would HTTP POST to rest-1.v1/Data.
POST /VersionOne/rest-1.v1/Data/Member HTTP/1.1
Host: www14.v1host.com
Content-Type: application/xml
<Asset href="/v1sdktesting/rest-1.v1/New/Member">
> <Attribute name="Name" act="set">Andre Agile</Attribute>
>
> <Attribute name="Nickname" act="set">Andre</Attribute>
>
> <Attribute name="Username" act="set">andre.agile</Attribute>
>
> <Attribute name="Email" act="set">andre.agile@mailinator.com</Attribute>
>
> <Attribute name="IsCollaborator" act="set">false</Attribute>
>
> <Attribute name="NotifyViaEmail" act="set">false</Attribute>
>
> <Attribute name="SendConversationEmails" act="set">false</Attribute>
>
> <Relation name="DefaultRole" act="set">
>
> ```
> <Asset href="/v1sdktesting/rest-1.v1/Data/Role/4" idref="Role:4" />
> ```
>```
> </Relation>
</Asset>
The result simply confirms the values that were specified got set as expected. The result also has the OID of the new Member asset. The following is representative of the XML response.
\<\?xml version="1.0" encoding="UTF-8"\?\>
<Asset href="/v1sdktesting/rest-1.v1/Data/Member/30633/50713" id="Member:30633:50713">
> <Attribute name="Name">Andre Agile</Attribute>
>
> <Attribute name="Nickname">Andre</Attribute>
>
> <Attribute name="Username">andre.agile</Attribute>
>
> <Attribute name="Email">andre.agile@mailinator.com</Attribute>
>
> <Attribute name="IsCollaborator">false</Attribute>
>
> <Attribute name="NotifyViaEmail">false</Attribute>
>
> <Attribute name="SendConversationEmails">false</Attribute>
>
> <Relation name="DefaultRole">
>
> ```
> <Asset href="/v1sdktesting/rest-1.v1/Data/Role/4" idref="Role:4" />
> ```
>
> </Relation>
```shell
</Asset>
3. Update Member
When we have the OID, we can update the existing Member when something changes. The following is a representative XML payload that we would HTTP POST to rest-1.v1/Data.
POST /VersionOne/rest-1.v1/Data/Member/30633 HTTP/1.1
Host: www14.v1host.com
Content-Type: application/xml
<Asset> <Attribute name="Phone" act="set">555-555-1212</Attribute> </Asset>
The result simply confirms the values that were specified got set as expected. The following is representative of the XML response.
\<\?xml version="1.0" encoding="UTF-8"\?\>
<Asset href="/v1sdktesting/rest-1.v1/Data/Member/30633/50714" id="Member:30633:50714">
<Attribute name="Phone">555-555-1212</Attribute>
</Asset>
4. Deactivate Member
Use meta.v1 to list the operations on the Member asset type.
<Server Base URI>/meta.v1/Member?xsl=api.xsl
The response should include something similar to the following list.
Delete : operation — validated by IsDeletable
Follow : operation — validated by CanFollow
Inactivate : operation — validated by CheckInactivate
InactivateCollaborator : operation — validated by CheckInactivateCollaborator
PromoteCollaborator : operation — validated by CheckPromoteCollaborator
Reactivate : operation — validated by CheckReactivate
ReactivateCollaborator : operation — validated by CheckReactivateCollaborator
Undelete : operation — validated by IsUndeletable
Unfollow : operation — validated by CanUnfollow
There are 2 operations that deactivate a member: Delete and Inactivate. We recommend Inactivate to remove system access but allow the Member to remain easily accessible for historical reporting. For more information see administrative advice on how to handle a departing team member. To execute the Inactivate operation, send an HTTP POST with no body using the op parameter set to Inactivate.
<Server Base URI>/rest-1.v1/Data/Member/30633?op=Inactivate
The response should be similar to the following.
<?xml version="1.0" encoding="UTF-8"?>
<Asset href="/v1sdktesting/rest-1.v1/Data/Member/30633/50715" id="Member:30633:50715" />
The returned Asset node indicates the asset was properly updated.
Related concepts