Synchronizing users via web services

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Security definition > Work Portal Security > Authentication > Advanced Authentication >

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,

 

What you need to do

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

 

1. Enabling the SOAP web services for your project.

Enabling the SOAP web services is done with Bizagi Studio as described at Enabling Bizagi API.

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

 

2. Developing a client to consume the Bizagi web services.

Once your project's web services are Enabled, consider that the web methods you need to use are called CreateUserAsString and saveEntityAsString (from the EntityManagerSOA web service).

For technical background or reference on this web method, refer to Create User and Save Entity.

 

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)

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

 

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:

 

Existing users synchronization example (useful as a scheduled invocation)

The following example updates information for one of the users created in the above example, by relying on the businessKey definition.

 

<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

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.

 

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).

 

Finally, make sure you programmatically schedule this web service invocation in order to make sure that your users are constantly being synchronized (e.g, disabled or new users taken into consideration appropriately).