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 ensure that users are initially registered in Bizagi's database before such users attempt 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.

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

 

Further detail on each is described below.

 

Steps

Follow these 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.

Note that it is recommended 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 method you will need to use is called saveEntityAsString (from the EntityManagerSOA web service).

For technical background or reference on this web method, refer to SaveEntitiesAsString.

 

How you would invoke and send out users information into Bizagi would be 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 plus username, fullName, contactEmail, enabledForAssignation and enabled).

 

<BizAgiWSParam>

<Entities>

<WFUSER>

 <fullName>Tom Hall</fullName>

 <userName>tomh</userName>

 <domain>agilityCorp</domain>

 <enabled>1</enabled>

 <enabledForAssignation>1</enabledForAssignation>

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

 <Organizations>

         <idOrg key="1"/>

 </Organizations>

</WFUSER>

<WFUSER>

 <fullName>Martha Lewis</fullName>

 <userName>marthal</userName>

 <domain>agilityCorp</domain>

 <enabled>1</enabled>

 <enabledForAssignation>1</enabledForAssignation>

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

 <Organizations>

         <idOrg key="1"/>

 </Organizations>

</WFUSER>

<WFUSER>

 <fullName>Piotr Blanter</fullName>

 <userName>piotrb</userName>

 <domain>agilityCorp</domain>

 <enabled>1</enabled>

 <enabledForAssignation>1</enabledForAssignation>

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

 <Organizations>

         <idOrg key="1"/>

 </Organizations>

</WFUSER>

</Entities>

</BizAgiWSParam>

 

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

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 plus organizational definitions such as the area and location (the default ones), and also further n-m details which include roles, skills or positions (set to 2 pre-defined roles, no skills and the default position).

 

<BizAgiWSParam>

<Entities>

<WFUSER>

 <fullName>Juliette Leroy</fullName>

 <userName>juliettel</userName>

 <domain>agilityCorp</domain>

 <enabled>1</enabled>

 <enabledForAssignation>1</enabledForAssignation>

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

 <Organizations>

         <idOrg key="1" />

 </Organizations>

 <idArea>1</idArea>

 <idLocation>1</idLocation>

 <Roles>

         <idRole key="1" />

 </Roles>

 <Roles>

         <idRole key="9998" />

 </Roles>

 <Positions>

         <idPosition key="1" />

 </Positions>

 <Skills />

</WFUSER>

</Entities>

</BizAgiWSParam>

 

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

Note 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

 

 

User creation example while also creating new organizational definitions

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

 

<BizAgiWSParam>

<Entities>

<WFUSER>

 <fullName>John Garcia</fullName>

 <userName>johng</userName>

 <domain>agilityCorp</domain>

 <enabled>1</enabled>

 <enabledForAssignation>1</enabledForAssignation>

 <contactEmail>johng@agilityCorp.com</contactEmail>

 <Organizations>

         <idOrg key="1" />

 </Organizations>

 <idArea>

         <areaName>Research</areaName>

         <areaDisplayName>Research and innovation</areaDisplayName>

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

 </idArea>

 <idLocation>1</idLocation>

</WFUSER>

</Entities>

</BizAgiWSParam>

 

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

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

 

Existing users synchronization example (useful as a scheduled invocation)

The following example updates information for the one same user 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>

 

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

 

Important notes

Consider:

You should ensure that the following values are not repeated across your users (these values should be unique): contactEmail for number one, and the combination of domain plus username as well.

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, ensure you programmatically schedule this web service invocation in order to ensure that your users are constantly being synchronized (e.g, disabled or new users taken into consideration appropriately).