Please note this tool was originally released under our legacy AuthAnvil brand.
How to Manually Create a Web-Workflow
This document outlines how to create a web workflow without the use of the web recorder plugin. This document also assumes that you have read and are familiar with the document pertaining to the the workflow editor.
This document also assumes that you have the most up to date version of SSO installed. (At the time this document was written, SSO version is 4.6.0)
While the web recorder is a powerful tool, there exists certain circumstances where it is simply unable to create the workflow correctly, therefore resulting in a workflow that does not function, which in turn requires the workflow to be created manually.
More information on the web recorder located here.
Workflow components
When you open the workflow editor for the first time, you will be met with a generally blank screen with the following items showing.
On the left hand side of the screen you will find the basic components of any website workflow.
Although a successful workflow can be created without all of the components being involved, there are some key components that will exist in every workflow.
-
Navigate to Page
-
The “Navigate to Page” seems pretty self explanatory, you need to provide a Url for the workflow to go to when you select it. This Url will generally be the Url of the page which holds the entry fields for logging in to the web site.
-
Note: All Urls must include the full prefix for or https://
-
Set Form Field :
-
Key – The identifier of a form field (i.e. <input name=”username“> or <input id=”username“>)
-
Value – A label to identify this field when viewed in the synchronization page of AuthAnvil Password Server. Note: Must be unique from any other Value fields in this Sequence
-
Input Type – The type of the HTML input element (i.e. <input type=”text” name=”username”>)
-
Form Find by – Defines the form that this element will be linked with, either by Name or ID (i.e. <form id=”form1“> or <form name=”loginform“>)
-
-
Define an element inside an HTML form using the following parameters:
-
Once the workflow has navigated to the login Url, the entry fields need to be clarified. Each site will require two entry fields to be defined, one for the Username and one for the password.
-
Submit Form:
-
Actions – Form will be submitted to this Target Url using either the POST or GET method (i.e. <form id=”form1″ action=”submit.asp” method=”POST”>)
-
Action Variable – A label to identify this field when viewed in the synchronization page of AuthAnvil Password Server. If defined, it will allow you to specify the form “Action” Url inside AuthAnvil Password Server. Note: Must be unique from any other labels in this Sequence
-
Submit Value – An identifier representing the proper submit button for the form. This is to differentiate from other buttons or submit values on a page that may perform other actions like JavaScript functions
-
Form Find by – Defines the form that will be submitted, collecting all of the form fields tied to this form by either Name or ID (i.e. <form id=”form1″> or <form name=”loginform”>)
-
-
Define the context for submitting the HTML form using the following parameters:
-
The Submit Form action is used in much the same way that pressing a button on a login screen is used. What the workflow does is calls the action (normally a “POST” action) behind the scenes to simulate this button pressing.
-
Validate Page:
-
Select an element on the page to use as validation that the Workflow has completed successfully. This will normally be a “Log Out” link verified by text, Url, or name, as a “Log Out” button will not display until you are successfully logged in.
NOTE: The above screenshots are only as examples of the sequence in which these components are added.
Component mapping and Creating a Workflow
Now that the general components of the workflow have been identified, how do they map to what is on a website?
Websites are made up of elements such as text boxes, buttons, text fields, hyperlinks, and images among many others. To start mapping these elements to the components of the workflow, we need to first start where the workflow starts, at the Navigation Url.
For the following example, we will use the general login page for Amazon.com, and Google Chrome as the browser.
-
Drag and drop the “Navigate to Page” component to the workflow as shown above.
-
Copy the Url from the login page and paste it into the “Url” area of the Navigate to Page” component.
Note: Some login pages produce large login Urls. It may be required that the Url be trimmed, and in some cases, the SQL database Url limit be increased. If you attempt to make the Url shorter, ensure that once you are finished that it still directs you to the desired Url.
-
Once on the Login screen, right click on the Username field, then left click on “Inspect Element”
-
You will then see the object explorer window as seen below
-
You will notice that a line in the inspector is highlighted, and when you move your mouse above that line, the Input area for the username (or in this case the e-mail address) becomes highlighted as well. This line identifies that element, however, now we need to figure out what is needed for the workflow.
-
Move forward with dragging and dropping the first of the two “Set Form Field” components under the Navigation component.
-
If possible, have the webpage and the workflow editor side by side so that we can enter in the information needed.
-
With the workflow editor and the website beside each other, you will be able to start filling in the required fields. We typically like to map each field by the element ID, if we are unable to locate that ID, or it does not exists, then we use the name, if that fails, then by input value, then class. In the example below we are able to map by ID, use the Name element to fill in the value, and set the Input type to email. The next are to fill in would be the “Form Value”, which can be found in the cookie tracks at the bottom of the element inspector, and we will find that form by the ID.
-
Once these areas are filled, we can move forward with adding the second “Set Form Field” component to the workflow, which will then cover the password element of the webpage.
-
On the website, right click on the password field and select “Inspect Element” to set focus on the password field line in the element inspector.
-
Much like the Email input field, all the characteristics are held within the line for that element. The input type is password, we find it by it’s ID, the name is the value and it exists on the same form as the previous component.
-
At this point in the workflow, we can test to ensure that we have the correct settings, without having to worry about an account being locked out, or even having an account. What our main concern is that the website fields get populated. The workflow should have the following components added with the corresponding values before proceeding:
-
At the top of the screen, beside the big bold lettering of “Workflow Designer”, greyed out there is an area called “Workflow Validator”. Select this area to test the workflow to ensure that the credentials are being added to the right areas.Add a fake username and password when you can, then select the “Try Logging in” button.
-
The validator will fail, mostly due to the last step of the workflow not being a validate page step, which for all intents and purposes, we aren’t worried about at this point. What we do want to do is verify that the Email (username) and password fields were populated with the information we entered on the left. Scroll down to the bottom of the page which should show you the last step of the workflow, aka the password field.
-
The above image proves that the fields have been successfully mapped and what remains now, is to add the final action ot our workflow, which is the Submit action.
-
Select the “Workflow Designer” title at the top to get back to the editor area.
-
Drag and drop the “Submit Form” component to the end of the workflow, then go to the website, right click on the “Sign in using our secure server” button and select “Inspect element”. The button properties should now be highlighted in the element inspector window.
-
Finding the action is a bit more in-depth, so we’ll cover that last and concentrate on the Submit value, and the form information. We already know what form this button exists on, so we can fill that in along with the fact that we are looking it up by ID. The Submit Value however, is also easy to find as it’s simply the id of the button, which also means that we are finding this element by ID.
-
To find the submit value, click on the form name in the cookie tracks at the bottom of the screen. This will take you to the main declaration for the frame itself. In this area, locate the item named “action”. In this case, its followed by a Url.
-
Copy the Url that is shown there into the Submit action of the workflow and that should be enough. Since we are already on the main website, the full Url isn’t typically required, therefore you could get away with adding only the “ap/signin” to the action potion.
-
The difference with the Submit Form action and the other components is that the only way you can see if you got it correct in the Workflow Editor, is to have another step/ component afterwards. To complete the testing of the workflow, we need to have some sort of validation, therefore, in the workflow editor, drag and drop the “Validate Page” component, to just under the Submit Form component.
-
The purpose of the validate page component, is to confirm that the workflow is functioning correctly, by looking for a website attribute that would only be available upon successful login. Although there are 7 different validation attributes that can be chosen, the easiest ones to use would be “Link with text” and “Page Url is as expected, no redirects”
-
For this example, we will choose “Link with Text”, simply because there will more than likely be a link named “logout” or “Signout” or something to that effect, and because this serves as more of a test component to ensure the Submit Form option works than anything else.
-
Once we have the Validate Page component added, we can then move forward and test the workflow again on the “Workflow Validator” page of the editor.
Note: Remember that you will more than likely get a “Failed” response at the top of the page, which is ok as we are more interested in ensuring the Submit Form component functions
-
Since in this example, we are using invalid credentials, my workflow will always fail at the validation, and will never actually sign in. This is still a good response as it does prove the workflow is functional.
-
Once we confirm the workflow functions, move back to the “Workflow Designer” area, and save the workflow to a location on your hard drive for upload into Password server.
Uploading for Testing in SSO
Although workflows are accessed and used through the SSO portal, they must first be uploaded into Password server so that they are available in the catalog.
To do this, log into Password Server and perform the following tasks:
-
Browse to “Admin > App Catalog” Then Select “Custom Apps”.
-
Select the “Upload Workflow” button on the far right.
-
In the popup window, Select the “Choose Files” button, then browse to the location in which you saved the workflow you created, select Open, and set a Display name for the Workflow and finally select the “Add Workflow(s)” button to complete the upload process.
-
Once the workflow is uploaded , you will be left in the “Allowed Apps” screen. If any changes are required to be done to the workflow, you have the ability to upload the changed workflow from this screen.
-
Open a new Web-browser window and log into your SSO portal.
-
Click the “Add new Application” button on the right side of the screen.
-
In the popup window, select the workflow you just created ...
-
Enter in your credentials to log into that website and press the “Add Application” button
-
Once added you will now have an icon on in you SSO portal to be used to log into the website.
Additional settings / components
Until now we’ve only touched base on a few of the key components that are available within the Workflow editor, however there are times where you may find you need more functionality from the workflow itself. This is where the following components come into play.
-
Click: This component simulates the clicking of an item on a web page such as a generic button, or an entry field for a password to set focus on that field.
-
Comment: Add text comments to provide information when reading through the Workflow. This step does not affect the execution of a Workflow
-
Delay: Wait for a certain number of seconds before continuing through the Workflow. Most steps require validation before they proceed so a delay may only be necessary when a special element takes longer to load than the page itself.
-
Set User Agent: Specify the user agent (browser) to simulate when connecting to the web pages. This can be used to provide a different visual display when logging in, or even to define a mobile browser to cause the target page to display differently.
Of the above additional actions, the most commonly used is the Click. With this component there are a couple of other factors that need to be configured that are not shown on the screen when the component is added. accessing the properties area is a must and is outlined below.
Configuring “Click”
For this example, although it is not required, I will add this to the Amazon workflow that was created above.
-
Drag and drop the “Click” component to just above one of the fields identified by the “Set Form Field” component.
-
Change the “Find…” by portion to be “Find element by ID”. Since we already have this information for the form, fill in the Value to be that of the ID, and fill in the “Type” as shown below.
-
On the far right hand side of the screen, you will notice an ellipse, to access the properties area, hover your mouse over top of the ellipse, left click and drag it towards the center of the screen. The properties of the component that is highlighted will be shown.
-
When adding a click action, the “Form Value” and “Key” aren’t automatically populated, and therefore will need to be manually configured.
-
Form Value is the equivalent to the Form Value in the “Set Form Field” component just after the Click step.
-
Key is the equivalent to the Key in the “Set Form Field” component just after the Click step.
-
The finished configuration can be seen below.
-
Once a click step has been added to a workflow, there are two ways to be sure that it is configured correctly.
-
Once the workflow is updated, SSO still tries to open the website without giving any errors
-
All other steps afterwards function correctly, resulting in a successful login.
Troubleshooting
Issue: When trying to access a workflow in SSO, I receive the following error:
Cause: The URl that has been placed into the Navigate to Page component has more than the 200 character limit that is in the Database.
Resolution #1: Upgrade the version of SSO as it will update the tables to accept longer URLs
Resolution #2: Update the “AudienceUri” column limit in the “SSO_ServiceProviderAudienceUri” table & update the “AudienceUri” column limit in the “SSO_ServiceProviderAudienceUri” table & update the “ReplyToUrl” column limit in the “SSO_ServiceProvider” table to be 3000 from 200.
(SQL statement examples)
Alter Table SSO_ServiceProviderAudienceUri Alter Column AudienceUri nvarchar(3000)
Alter Table SSO_ServiceProvider Alter Column ReplyToUrl nvarchar(3000)
Issue: When trying to access a workflow in SSO, I receive the following error:
Cause #1: Set Form Field is missing, or Click Step component has not been configured correctly.
Resolution: Add Set Form Field to workflow or Configure the Form Value and Key properties for the Click step. (see above for information on how to do this)
Cause #2: SSO version is older than 4.6.0
Resolution: Upgrade SSO version
Cause #3: SSO version 4.6.0 but the old multi-tenancy dll was put in place after the upgrade
Resolution: reinstall the upgrade for SSO
Issue: I am unable to add and application to Password server
Cause: Insufficient privileges to access that area of Password Server
Resolution: Contact your system administrator for assistance gaining access.
Issue: I am unable to add an application to SSO
Cause #1: Insufficient privileges in Password server
Resolution #1: Contact your system administrator for assistance gaining access
Cause #2: You are accessing your SSO portal using http, rather than https
Resolution #2: Change the Url you are using to log into SSO to use Https