Synchronizing users via web services

<< Click to Display Table of Contents >>

Navigation:  Environments identity and access management > Synchronizing users >

Synchronizing users via web services

Overview

Bizagi supports different authentication types, some of which are actually integrated authentication mechanisms which rely on external identity providers such as federation services or LDAP systems.

Regardless of the type of authentication chosen, you will need to make sure that users are initially registered in Bizagi's database before such users attempt to log in the Work portal.

 

Initially registering the users means creating or synchronizing them in Bizagi's WFUser entity, and for this, you may rely on Bizagi SOAP web services.

 

note_pin

Note that specifically for the LDAP authentication type, you may rely on the LDAP Import module as described at Importing LDAP users,

 

Before You Start

To use Bizagi SOAP web services for this purpose, consider the following outline of steps:

 

Enabling the SOAP web services for your project

We recommended you to use the web services featuring WS-Security support, for which you will need to considering using X509 certificates.

 

Have a client to consume the Bizagi web services

Once your project's web services are enabled, consider you need to have a client to invoke SOAP methods. For example, you can use SOAPUI or another client developed by you. The following sections describe examples for creating or updating users.

 

What you Need to Do

Depending on what you need to do, you have to use a specific method of Bizagi's SOAP web services:

 

To Create New Users

To create new users you need to use the CreateUserAsString method. For further details about this method click here. In the current article you can see a series of examples of the XML that needs to be sent when creating a new user:

 

Simple user creation example (useful for initially populating user data)

Comprehensive user creation example (considers reusing organizational user definitions like roles or areas)

Create users with customized user properties

 

To Update Existing Users

To update the information of existing users you need to use the saveEntityAsString method. See more details about this method here. In the current article you can see a series of examples of the XML that needs to be sent when updating an existing user:

 

Update simple information of existing users

Updating user examples while also creating new organizational definitions like roles or areas

Update a customized user property

Assigning users Stakeholders

 

Creating Users

To create users, invoke the web method called createUserAsString. Invoke and send out users information into Bizagi as illustrated in the examples below:

 

Simple user creation example (useful for initially populating user data)

The following example creates three users with the basic mandatory information (organization, domain and username, fullName, ContactEmail).

 

<BizAgiWSParam>

<Entities>

<WFUSER>

 <BasicInformation>

         <FullName>Tom Hall</FullName>

         <UserName>tomh</UserName>

         <Domain>agilityCorp</Domain>

         <ContactEmail>tomh@agilityCorp.com</ContactEmail>

         <Organizations>

                 <Organization>1</Organization>

         </Organizations>

 </BasicInformation>

</WFUSER>

<WFUSER>

 <BasicInformation>

         <FullName>Martha Lewis</FullName>

         <UserName>marthal</UserName>

         <Domain>agilityCorp</Domain>

         <ContactEmail>marthal@agilityCorp.com</ContactEmail>

         <Organizations>

                 <Organization>1</Organization>

         </Organizations>

 </BasicInformation>

</WFUSER>

<WFUSER>

 <BasicInformation>

         <FullName>Piotr Blanter</FullName>

         <UserName>piotrb</UserName>

         <Domain>agilityCorp</Domain>

         <ContactEmail>piotrb@agilityCorp.com</ContactEmail>

         <Organizations>

                 <Organization>1</Organization>

         </Organizations>

 </BasicInformation>

</WFUSER>

</Entities>

</BizAgiWSParam>

 

Take into account that a user may belong to more than one organization, though the above example considers linking the users to the default organization which is already registered in any Bizagi project (additional organizations need definition and so you would have to assign IDs accordingly for the key definition).

By default, the users created with the basic mandatory information will have activated the parameters Enabled and Enabled for assignation.

It is required that users belong at least to one organization; otherwise such user will not be able to perform actions in the Work portal (such as creating cases, running queries, etc).

A successful web service response will send back the three unique system IDs created for each user:

 

SaveEntityWFUser

 

Comprehensive user creation example (considers reusing organizational user definitions like roles or areas)

The following example creates one user with basic information and organizational definitions such as area and location (the default ones), user information (password, picture, if the user is enabled and enabled for assignation), and also further n-m details which include roles, skills or positions (set to 2 pre-defined roles, and the default position).

 

<BizAgiWSParam>

<Entities>

<WFUSER>

 <BasicInformation>

         <FullName>Juliette Leroy</FullName>

         <UserName>juliettel</UserName>

         <Domain>agilityCorp</Domain>

         <ContactEmail>juliettel@agilityCorp.com</ContactEmail>

         <Password>Bizagi123</Password>

         <Picture>/9j/4AAQSkZJRgABAQEAYABgAAD/4QHGRXhpZgAATU0AKgAAA..</Picture>

         <Organizations>

                 <Organization>1</Organization>

         </Organizations>

 </BasicInformation>

 <UserConfiguration>        

         <Roles>

                 <idRole key="1"></idRole>

                 <idRole key="9998"></idRole>

         </Roles>

         <idArea key="1"></idArea>

         <idLocation key="1"></idLocation>

         <Positions>

                 <Position>1</Position>

         </Positions>

         <Enabled>1</Enabled>

         <EnabledForAssignation>1</EnabledForAssignation>

         <IdDelegate>204</IdDelegate>

 </UserConfiguration>

</WFUSER>

</Entities>

</BizAgiWSParam>

 

Make sure you send the user's profile picture encoded using Base64. You can encode this file using any of the free online encoders or developing one from scratch.

A successful web service response is the same as the one depicted above.

Take into account that a user may belong to one area and location at most; but may belong to more than one roles, skill or position. When considering these definitions, acknowledge that you need to define them previously and look up their IDs (to modify the key definition):

 

SaveEntityOrganization

 

Create users with customized user properties

Bizagi allows to create customized user properties,  for example Age, or Authority Level, when default properties are not enough to create profiles of your users. Refer to User Properties. For example, Age has been created in Studio as a custom property:

 

CreateUser_01

 

To create a user with customized user properties use the following example. If you need to include other customized properties, include them within the UserConfiguration tag.

 

<BizAgiWSParam>

<Entities>

<WFUSER>

 <BasicInformation>

         <FullName>Tom Hall</FullName>

         <UserName>tomh</UserName>

         <Domain>agilityCorp</Domain>

         <ContactEmail>tomh@agilityCorp.com</ContactEmail>

         <Organizations>

                 <Organization>1</Organization>

         </Organizations>

 </BasicInformation>

 <UserConfiguration>

         <Age>35</Age>

 </UserConfiguration>

</WFUSER>

</Entities>

</BizAgiWSParam>

 

If the name of the property is wrong or does not exist, Bizagi creates the user without that property.

 

If the Customized User Property is a relationship to another entity, you must send the record's ID. Bear in mind that IDs can be different between the development and production environment. For example, you have the following User Property:

 

CreateUser_02

 

You must look for the Id of the record you want to send when creating the user.

 

CreateUser_03

 

For example, If you want to create a user with Intermediate Authority Level, you must send the ID = 2 as shown in the next example. The name of the tag is:

 

id + the name of the user property, for example idAuthorityLevel.

 

<BizAgiWSParam>
<Entities>
<WFUSER>
  <BasicInformation>
    <FullName>Cam</FullName>
    <UserName>Cam</UserName>
    <Domain>domain</Domain>
    <ContactEmail>tomh@agilityCorp.com</ContactEmail>
    <Organizations>
        <Organization>1</Organization>
    </Organizations>
  </BasicInformation>
  <UserConfiguration>
    <idAuthorityLevel>2</idAuthorityLevel>
  </UserConfiguration>
</WFUSER>
</Entities>
</BizAgiWSParam>

 

Updating users

To update users, invoke the web method called saveEntityAsString. Invoke and send out users information into Bizagi as illustrated in the examples below:

 

Update simple information of existing users

The following example updates information an existing user, by relying on the businessKey to search the username and domain of the user.

 

<BizAgiWSParam>

<Entities>

<WFUSER businessKey="userName='juliettel' AND domain='agilityCorp'">

 <fullName>Juliette Leroy-Brown</fullName>

 <userName>juliettel</userName>

 <domain>agilityCorp</domain>

 <enabled>1</enabled>

</WFUSER>

</Entities>

</BizAgiWSParam>

 

Keep in mind that the field we are updating is merely the fullName, and because we don't need to update other information, we may choose to skip its definition (so that existing values are kept).

A successful web service response is the same as the one treated in both examples above (either being created for the first time or being updated, the response sends back the ID of each record involved by the invocation).

 

Updating user example while also creating new organizational definitions like roles or areas

The following example updates a user with basic information plus a new area (you may create organizational definitions which do not have an n-m relationship with the user).

 

<BizAgiWSParam>

<Entities>

<WFUSER businessKey="userName='juliettel' AND domain='agilityCorp'">

 <idArea>

         <areaName>Research</areaName>

         <areaDisplayName>Research and innovation</areaDisplayName>

         <areaDescription>In charge of developing new ideas</areaDescription>

 </idArea>

</WFUSER>

</Entities>

</BizAgiWSParam>

 

A successful web service response is the same as the one depicted above.

Keep in mind that with the example above, Bizagi automatically generates the ID for the new area and associates it to the user.

As mentioned above, creating organizational definitions such as: roles, skills, positions or organizations, need to be manually done in Bizagi beforehand.

 

Update a Customized User Property

If you have to update a customized user property, you have to send the tag of the property's name within the XML like the following example:

 

<BizAgiWSParam>

 <Entities>

         <WFUSER businessKey="userName='juliettel' AND domain='agilityCorp'">

                 <Age>35</Age>

         </WFUSER>

 </Entities>

</BizAgiWSParam>

 

If the property is a relationship with an entity, you must use the Id of the record to set. For example, if you have the Authority Level User Property.

 

CreateUser_02

 

You must look for the Id of the record you want to update to the user.

 

CreateUser_03

 

To update a user with an Intermediate Authority Level, you must send the ID = 2 as shown in the next example. The name of the tag is:

 

id + the name of the user property, for example, idAuthorityLevel.

 

<BizAgiWSParam>

 <Entities>

         <WFUSER businessKey="userName='juliettel' AND domain='agilityCorp'">

                 <idAuthorityLevel>2</idAuthorityLevel>

         </WFUSER>

 </Entities>

</BizAgiWSParam>

 

Assigning users Stakeholders

It is possible to add the StakeHolders node on your request to set a Stakeholder for a given user. The following example uses the businessKey definition to do so:

 

<BizAgiWSParam>
<Entities>
<WFUSER businesskey="username='juliettel'">
  <StakeHolders>
      <stakeholderName1>
          <stakeholderAttribute>value</stakeholderAttribute>
      </stakeholderName1>
      <stakeholderName2>
          <dummy></dummy>
      </stakeholderName2>
  </StakeHolders>
</WFUSER>
</Entities>
</BizAgiWSParam>

 

Keep in mind that Stakeholders may or may not contain attributes. In case you wish to update this information, the attribute must be added as a node for the Stakeholder. In this case the attribute stakeholderAttribute for stakeholderName1. Whereas if the Stakeholder has no attributes or no attribute is going to be updated, a dummy node must be included. In this case the node dummy for stakeholderName2.

 

Important notes

Make sure that the following values are not repeated across your users (these values should be unique): ContactEmail for number one, as well as the combination of Domain and username.

Enabled should vary whether or not a given user in your users repository is disabled.

For on-premise Bizagi projects, it is important you consider the number of licensed users (which directly limits the amount of enabled users).