Support Import

An Example on User Libraries

Read Data from Excel File

Reading Data from Excel Files involves four standard steps that you are very likely to repeat a lot while you are working with Softomotive products. At this example we are going to show you how User Actions can help you avoid repeating yourself while using your favorite code components across all your Processes in an instance!

Identifying the opportunity:

Identifying the chance to use a User Action is important as it will give you the opportunity to make your life easier and productive. Reading data from an Excel File can be a good Case Study as it makes use of four standard Actions:

-Launch an Excel Instance using a specified Path,

-Set an Active Excel Worksheet using a specified index,

-Get First Free Column/Row from the specified Worksheet and

-Read & Save your Data!

Thinking in terms of Input & Output:

Transforming these four Actions into one means that the User that will use this compacted script, should be able to enter the same amount of Input it would have been otherwise asked to provide for the smooth execution of this sequence of Actions. In other words, in order to compact our 4 Actions script into a single Action, we need to make sure that we provide these interactive "slots" in this new User Action's interface so everything can fall into place harmoniously.

In the same spirit we need to ensure that the output of our Action is available somehow to other segments of our code. User Actions have been designed to allow you to compartmentalize your code in a manner that is handy and functional while offering you the full interactive interface of a predefined Action.

A 3-step procedure:

Having said that, we are ready to jump on how to create, commit and publish our User Action!

1. Open the User Library Designer

Opening the User Library Designer (or ULD) is the first step in order to create and share your User Action. The following diagram shows you in detail how you can access the ULD from Process Studio.

User_Library_Exxample_PR_2a1.PNG

As you can see we have decided to name our Library "Automate Excel". User Libraries are containers of User Actions, so you might find it convenient to give them descriptive names that make the grouping and allocation of User Actions intuitive and easy to work with.

2. Developing your User Action

In order to start working on our first User Action - in this case "Read Data from Excel File"- you need to direct your attention on the User Actions pane.

As you can see, the program has been anticipating your intentions and has already created a User Action by the name User Action 1. However by pressing the fourth button from the left in the pane's toolbar (Edit User Action Data) we can rename whichever User Action is highlighted in the tree-view. So, by left-clicking once on User Action 1 and then pressing the aforementioned button, we can observe the Edit 'User Action 1' dialog box popping in our screen, giving us the opportunity to rename the specific User Action into "Read Data from Excel File".

User_Library_Exxample_PR_2a2.PNG

Left-clicking on the expand (+) of the User Action in the tree-view will reveal two branches: (a) the Input Parameters and (b) Output Parameters sub-items. Input and Output Parameters are the terms we use in order to describe the interactive slots that helps us define the structure of what should be familiar by now, Action's Properties dialog box. If you are not familiar with the Properties dialog box you are strongly advised to spend some additional time reading our documentation on Process Designer before venturing into User Libraries.

the-properties-dialog-box.png

In order to add or remove Parameters, we need but to double-click on the appropriate branch (Input when we desire to construct an interactive box through which the User will be able to insert information and output when we wish to create an outlet that will give us the opportunity to export the outcome of our Action inside the scope of a larger script)

Double-clicking on Input Parameters will result into the Edit 'User Action 1' Parameters dialog box:

edit-ua-properties.png

For the purposes of our example, we need to create at least two Input Parameters in order to allow users to state which file and Worksheet they want to extract data from (the xls's path and the index number or name of the Worksheet).

To do so, as it has been explained in detail before, we'll press the blue/white plus icon at the bottom-left and then clarify that the addition concerns an Input Parameter. At this point, the right hand-side contents of the box will become accessible (de-greyed) and we'll be free to enter the name of the Parameter, the Variable that will hold its value, its Type and specify whether it is a List or not, along with some optional Help Text.

filled-ua-properties.png

After pressing OK, we'll repeat the exact same process in order to add another Input Parameter that will define the index number of the Worksheet we wish to extract data from.

filled-ua-propertiesii.png

Now, we are ready to create the sequence of Actions in our Workspace (we won't go to any details here since we are assuming that the reader is already familiar with the basics of creating a simple process). The end result should look something like that:

ua-workspace.png

At this point we are ready to introduce an Output Parameter following the exact same process we did for the Input Parameters except clicking the Output option instead of the Input option.

output.png

At this point the Treeview should look something like that:

complete-tree-view.png

Now, in order to test our User Action (or UA) we can Run it as Function from Main, after having set appropriate values for the variables representing our Input Parameters (for that purpose we can use Set Variable Actions).

running-it-from-main.png

3. Publishing your User Library

Before you are ready to share your Action with your collegues or the PR community, you first need to save and commit your changes as a new Version.

User Actions follow as all script development in PR, a Lifecycle of development, approval and publishing you must surely know about by now through Processes.  

So to Save and Commit the changes on your Process Designer simply click first on the little menu arrow by the Save option on ULD and then the Save And Commit item.

User_Library_Exxample_PR_2a3.PNG

This will result to a Commit Process dialog box, that we'll fill out in the following manner:

commit-process.png

Notice that we are about to click Commit without leaving a Message, since this is optional and meant to help you and your colleagues keep track of your development efforts.

Now that we have committed our changes, it is time to close the ULD and finally Publish Automate Excel, the User Library that holds our beloved first User Action.

To do so, we'll head to Process Studio, highlight the Library of our choice (Automate Excel) on the main Viewport and then click on the Publish button.

User_Library_Exxample_PR_2a4.PNG

This will result on the Version to Publish dialog box that will finally publish our Library, making it instantly available to all Processes of our installation.

version-to-publish.png

We can verify that our Library has been published by either clicking on the Version Control button that will allow us to check the History of our Library, or simply check the Last Published column on the central Viewport:

User_Library_Exxample_PR_2a5.PNG

The Ultimate Test: Using our User Action

Now we are ready to use our User Action into any Process we want. To do so in our PR installation simply open up a new Process on Process Designer (we've done so through the creation of a Testing my User Action).

Having done so, simply check the very last Folder at the bottom of the Actions pane:  

User_Library_Exxample_PR_2a6.PNG

As the diagram shows having located the UA, what is left to happen is simply to Drag and Drop the Action to your Workspace and pass the values of Path and Worksheet into its Properties before you are 100% set to use your Action.