How to Use the WEBcnx.API Reference Guide

As soon as you need to start doing anything moderately complex with Workflow, you will soon find you need more information about the various concepts used in WEBcnx. Maybe you want to associate the project your design request created to your Job, but how do you find the Job of a Task in workflow? The API Reference Guide explains everything you need to dig deeper into WEBcnx, accessing everything you need to build even the most complex of workflows.

Getting Started

Before getting into the details of the WEBcnx API, you should first know the basics of the terms used and how they relate to each other. This is really important as you navigate your way through finding a task, accessing the properties of that task and then using any of the permitted functions on it.

Members

A Task has lots of common attributes, such as an Assignee, a Customer, a Subject, etc. A User also has many attributes, a Name, Email address, Site, etc. Almost everything you look at in WEBcnx has a set of common attributes that can be used in Workflows; Addresses, Customers, Documents, User Groups, etc. These are all Properties.

You can also ask a Task for specific information such as getting a list of Clockings or the value of a Custom Field, or ask it to perform a specific process such as clearing all subscriptions. These are Methods (or functions) and allow you to perform a specific process or procedure without having to write lots of code to do these common things.

Properties and Methods are all Members of a Class.

Classes

WEBcnx is made up of many different concepts; Tasks, Users, User Groups, Customers, etc. These "things" are all Classes.

Objects

If you view a specific Task or Customer in WEBcnx, you're looking at an Object. This is why we use the generic term "Object Dialog" for some of our dialogs in WEBcnx when we're being generic about the type of "thing" you're looking at.

Variables

If you want to reference an Object in workflow, we need to make the Workflow Diagram aware of the Object we're interested in and give it a name so that we have something to reference and help our workflow make sense. As a Task driven system, if your Workflow diagram is doing anything with Tasks, the use of the word Task used repeatedly all over your Workflow makes it really difficult to know exactly what it's referring to. If you want to reference more than one Task in a Workflow, something needs to differentiate them. For this reason, it's good practice to create Variables and give them sensible names; DesignRequest, SampleRequest, Job, etc.

Making Sense of It All

A simple example to help visualise this is to consider the people around us. We're all people. We all have names, an age, a height and weight, etc. We're all also unique. We can also do lots of things and some of those things are common to us all, eating, sleeping, breathing, etc.

A Person is therefore a Class. Our Person Class has the Properties; Name, Age and Height and our Person Class also has the Methods; Eat, Sleep, Breath and Move. Each instance of a person is an Object. You can now retrieve the Properties of an individual in a common way because every person has the same Properties. To help navigate through the various parts of this structure we use "Dot Notation", so Person001.Name = "Catherine" and Person002.Age = 39.

In WEBcnx, let's say we wanted to get the Job number of the Job that Design Request "DR1234" belongs to. 

• A Design Request is a type of Task (a Class).
• "DR1234" is a specific instance of a Design Request (an Object). In the API, this is called the "ShortName" of the Design Request and is the Task number displayed to users.
• A Task has Properties including Assignee, Customer, Job, ShortName and Subject.
• A Job is just another type of Task, which means that it has all the same Properties as any other type of Task.
• Assuming a DR1234 has been assigned to Variable, "DesignRequest", accessing DesignRequest.Job.ShortName will then give us the Job number (ShortName) of the Job that task DR1234 belongs to

API Class Reference

Using the API Reference Guide

Now you know the terminology and relationships between the various terms, navigating the Reference Guide becomes straightforward.

When you open the API Reference Guide, you will be shown the root level Namespace. This is the top-level collection of Classes and their Members. 

From here, you can either expand the tree in the Contents panel on the left, or click the Arden.WEBcnx.Api clickable link in the main panel.

From here, you can select any of the Classes that you want to explore and view the list of Task Members, their Properties and Methods. You can click any of the clickable links in the main panel to view more information.

Selecting any of the Properties or Methods in a Class to view the specific information about that Member.

Syntax

The Member Syntax describes how to use the Member and what sort of data to expect. The type of data that a Member returns is described after the Member name. These are either:

• Simple data types
  • Boolean
  • Date/Time
  • Double or Real
  • Integer
  • Object
  • String
• Complex data types. Sometimes, a property of a Class could be another Class. For instance, a Task is created by a User (the Owner) and a User is also a Class that has its own Properties, including the Name. "Task.Owner.Name" will therefore give you the name of the Task's Owner as a String because the Name Property is of a simple String data type.

You need to know what the data type is of the property you want to use to ensure it's compatible with how you want to use it. If the CreateTask Workflow activity wants a Customer Object, you can't pass the Customer Name "ACME Inc." into it, as it's a String and just a Property of a Customer.

A new API reference document is published with each version of WEBcnx to reflect any changes in the API, as new classes, methods, or properties are introduced.
Therefore, make sure you're using the correct version of the documentation based on the version of your target WEBcnx installation.

Refer to the separate WEBcnx.Activities reference guide for documentation related to the activities available within the Workflow Designer. These activities are the common building blocks in any WEBcnx workflow, controlling which actions are taken.