API Functions
- Overview
- Web Server API
- Server API
- CustomField
- FolderListBlockFetchForSite
- FolderListSingleFetch
- FolderListSingleFetchSiteName
- GetBasicSessionData
- GetEventInformation
- GetEventTypeForEvent
- GetSessionData
- GetSiteData
- Presentation
- Role
- Session
- User
Overview
The Websydian Express API functions are the developers interface to Websydian Express. That is, when the developer at runtime needs to retrieve information about Websydian Express this is typically done by calling an API function.
The API functions are defined in the WSYAPI library model and are scoped under one of two functions:
- APIWebServer
- For API functions deployed on the web server.
- APIServer
- For API functions deployed on the backend (database) server.
Events
Apart from the "normal" values for *Returned Status, these API functions can also return the unique identification of a Websydian Express Event - this will always be a numeric value corresponding to an entry in the message log table.
If the function is successful it will always return *Returned Status = *Successful. As this is the case, it should in almost all instances be sufficient to just check whether the *Returned Status is successful or not after calling an API.
If you during your test need information about the error that has happened - use the message log in the administration interface to obtain the reason for the error.
Should you however want to use the information in the messages you can use the two following API functions to obtain the information.
This function will return the identification of the message (event) type. Based on this you can get the type of error, which the message belongs to. You will typically need this when you want to control the execution of program statements based on the errors returned.
In addition to the event type - this API also returns the text for the event.
You will typically use this API if you want to show an error message to a user or write it to a log file.
Universal events
There are a number of events that can be thrown by any API function. All of these are to some extent a symptom of some kind of system error - and should be reported as such.
EvF001 - Call to GetEventType failed
An attempt to call a basic runtime function has ended in error. This should only happen if the runtime object has been removed.
EvF002 - Error in function
This is an event that is thrown if a call to a function returns a call status. As used in the API's it will usually happen if the API function calls a service function - and this call results in a call status error.
EvF008 - Uncatched event
This event is thrown when a call from one runtime function to another has resulted in an unexpected return status. This is a system error.
EvF057 - Unknown Error type
This event is thrown if a call to a function has resulted in a returned status that can not be identified as a valid event or one of the Plex standard return codes.
Web Server API
Please be aware that these functions may NOT be called from server functions
API: GetCurrentPresentation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| PresentationSurrogate | FetchedData | Output | The unique identification of the current presentation. |
| TemplateSuffix | FetchedData | Output | The suffix used to specify that the HTML templates are belonging to the current presentation. |
| TemplateOverrideName | FetchedData | Output | The override name specified for the current presentation. |
| PresentationName | FetchedData | Output | The name of the current presentation. |
| PresentationComment | FetchedData | Output | Any comments specified for the current presentation |
| ProcessSurrogate | FetchedData | Output | The unique identification of the process that the presentation belongs to. |
| ProcessID | FetchedData | Output | The program name of the ProcessEntryPoint used by the process that the presentation belongs to. |
| ProcessType | FetchedData | Output | The type of the process that the presentation belongs to. The type can be either Business Process (literal value 4), Menu Loader (literal value 5), or Frameset Loader (literal value 6). |
| ProcessDescription | FetchedData | Output | The description specified for the process that the presentation belongs to |
| ProcessComment | FetchedData | Output | Any comments specified for the process that the presentation belongs to. |
| ProcessText | FetchedData | Output | The name of the process that the presentation belongs to. |
Description
This API can be used to retrieve information about the current presentation used by the process. The retrieved presentation surrogate can be used to fetch any property values specified for the presentation (using the server API's GetPresentationProperty and GetPropertiesForPresentation).
Events
API: PasswordUpdate
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Data | Input | The unique identification of the user. |
| UserPassword | Data | Input | The new password for the user. |
| ErrorMessage | Error | Output | A text describing the error. |
Description
This API can be used when a password is to be changed for a user. The API performs the same validation as the PasswordUpdateValidation.
If the validation is successful the password will be updated for the user specified by the user surrogate and the *Returned status field is set to *Successful.
If the validation fails *Returned status will be different from *Successful and the ErrorMessage field will contain a text describing the reason for the failure.
If you do not have the user surrogate for the user whose password you want to update you can call the UserSingleFetchSiteLogin with information about the site and the login name for the user to obtain the surrogate.
Events
API: PasswordUpdateValidation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Data | Input | The unique identification of the user. |
| UserPassword | Data | Input | The new password for the user. |
| ErrorMessage | Error | Output | A text describing the error. |
Description
This API can be used when a password is to be changed for an existing user. The API only performs validation - not any updates. The *Returned status field is set to *Successful if the validation is successful.
If the validation fails the ErrorMessage field will contain a text describing the reason for the failure.
If you do not have the user surrogate for the user whose password you want to update you can call the UserSingleFetchSiteLogin with information about the site and the login name for the user to obtain the surrogate.
As the PasswordUpdate function itself calls this validation function, you should only call this function if you want to make sure that the update will be successful before calling the update function (e.g. if you have a set of pages performing data capture - where the update itself must not be done before the last panel has been accepted).
Events
API: PasswordValidationForLogin
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Input | Input | The unique identification of the user. |
| UserPassword | Input | Input | The new password for the user. |
Description
The API validates whether the entered combination of user identification and password corresponds to the password registered for the user.
The *Returned status for the function will be set to *Instance not found if the user does not exist. If the password is incorrect the *Returned status will be set to *Error.
If you do not have the user surrogate for the user whose password you want to check you can call the UserSingleFetchSiteLogin with information about the site and the login name for the user to obtain the surrogate.
Events
API: ReloadSitePageGenerator
Interface
None
Description
Call this API if you have changed roles or user for the session and want to reload the site based on the new session information.
This can be used if you create a custom-made login functionality.
The API calls a PageGenerator that contains an event which reloads the site. In the HTML template WSLOAD used by this PageGenerator, this event is specified as having target ="_top" and the page includes JavaScript that executes this event automatically.
This template is delivered in the "basicsite" template folder. This template must be present in a folder in the folder list used by the session when the API is called - otherwise an error will be reported to the user and the site will not be reloaded.
In some cases, the user will see the page generated by the WSLOAD page for a moment before the reload is done. If you want to change the design of this page, you can do so by changing the template WSLOAD - but it is important that you do not remove the submit statement in the Initialization JavaScript and that the target for the event remains "_top".
The PageGenerator inherits from PageGeneratorNoPresentation, this means that you do not have to make a special version for each presentation, it is always the basic WSLOAD template that will be used.
Events
EvF036 - Session not found
API: UserCreate
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserFolderListID | Data | Input | The unique identification of the folder list the user should use (optional). |
| EmailAddress | Data | Input | The E-mail address of the user (Mandatory). |
| LoginName | Data | Input | The login name for the user (Mandatory). |
| FullName | Data | Input | The full name of the user (Mandatory). |
| UserSiteKey | Data | Input | The site, which the user should be able to access (Mandatory). Please note that if one person should be able to access several sites, he will have to have one user profile for each site. |
| UserPassword | Data | Input | The password for the user (Mandatory). |
| UserStatus | Data | Input | The state of the user (Mandatory). Valid values: Active (A), Inactive (I), TooManyFailedLogins (F). |
| CrtByUserSgt | Data | Input | The unique identification of the user creating the new user (Optional). |
| NumberOfErrors | Error | Output | The number of records in the ErrorArray variable. |
| ErrorMessage | ErrorArray(20) | Output | An array of text descriptions of the errors encountered during the validation. |
| UserSurrogate | Key | Output | The unique identification of the created user. |
Description
The function is used to create users without using the administration interface.
The function starts by calling the UserCreateValidation function that validates the input. If the validation is successful, the user is created, and the resulting user surrogate is written to the output variable Key, and the *Returned status is set to *Successful.
When an error is encountered during validation the *Returned status is set to a non-successful value, an error message is written to the ErrorArray and the number of errors is incremented with one. Please note that for certain system errors (missing objects etc.), it can happen that no messages will be written to the array. You should always use the *Returned status to evaluate the result of the call.
Events
API: UserCreateValidation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserFolderListID | Data | Input | The unique identification of the folder list the user should use (optional). |
| EmailAddress | Data | Input | The e-mail address of the user (mandatory). |
| LoginName | Data | Input | The login name for the user (mandatory). |
| FullName | Data | Input | The full name of the user (mandatory). |
| UserSiteKey | Data | Input | The site, which the user should be able to access (mandatory). Please note that if one person should be able to access several sites, he will have to have one user profile for each site. |
| UserPassword | Data | Input | The password for the user (mandatory). |
| UserStatus | Data | Input | The state of the user (mandatory). Valid values: Active (A), Inactive (I), TooManyFailedLogins (F). |
| CrtByUserSgt | Data | Input | The unique identification of the user creating the new user (optional). |
| NumberOfErrors | Error | Output | The number of records in the ErrorArray variable. |
| ErrorMessage | ErrorArray(20) | Output | An array of text descriptions of the errors encountered during the validation. |
Description
The API performs the necessary validation for the creation of a new user.
If the validation is successful *Returned status is set to *Successful.
If an error is encountered during validation the *Returned status is set to a non-successful value, an error message is written to the ErrorArray and the number of errors is incremented with one.
Please note that for certain system errors (missing objects etc.), it might happen that no messages will be written to the array. You should always use the *Returned status to evaluate the result of the call.
The following validation is performed:
User Status
The user status must be one of the values defined for the field ("Active", "Inactive", "TooManyFailedLogins").
Folder List
The folder list ID is optional but if it is used it must specify a defined folder list for the site the user is defined for. If you do not have the folder list ID you can obtain this by calling the FolderListSingleFetchSiteName server API or by calling the FolderListBlockFetchBySite server API.
If you do not specify a folder list for the user - the folder list for the user's sessions will be found based on the authorization of the user (see more about how the folder list is found for a session here).
This field is mandatory
Login Name
This field is mandatory. The combination of site key and login name must not already exist.
Full Name
This field is mandatory.
SiteKey
The site must exist.
Password
This field is mandatory.
Surrogate for creating user
The surrogate is optional, but if it is specified, the user must exist.
Events
Server API
API: CustomField.GetAllValuesForInstance
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| CustomFieldEntity | Position | Input | The entity the custom field is defined for. |
| InstanceKey | Position | Input | The unique identification of the record in the entity (converted to a character string). |
| CustomFieldName | Position | Input | The name of the custom field - used to position the retrieved list of name/value pairs. |
| Position | Control | Input | Specifies whether the data in the Position variable is used for positioning when fetching the data. |
| RowsFetched | Control | Dual | The number of fetched records in the output variable FetchedData. |
| CustomFieldName | FetchedData(64) | Output | The name of the retrieved custom field. |
| Value | FetchedData(64) | Output | The value registered for the custom field for the specified record. |
Description
The API provides all the data registered as custom fields for a specific record.
The API retrieves all of the custom fields that has been specified for an entity. For each of these custom fields, the value registered for a specific record in the entity is returned together with the name of the custom field. If no value has been registered for a combination of entity, record, and custom field - blank is returned for the value.
Events
API: CustomField.GetInstancesForValue
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| CustomFieldSiteKey | Position | Input | The current site. |
| CustomFieldEntity | Position | Input | The entity the custom field is defined for. |
| CustomFieldName | Position | Input | The name of the custom field. |
| Value | Position | Input | The value to retrieve instances for. |
| InstanceKey | Position | Input | The unique identification of the record in the entity (converted
to a character string).
Used to position the list of retrieved instances. |
| Position | Control | Input | Specifies whether the data in the Position variable is used for positioning when fetching the data. |
| RowsFetched | Control | Dual | The number of fetched records in the output variable FetchedData. |
| InstanceKey | FetchedData(64) | Output | The unique identification of the record in the entity specified by Position<CustomFieldEntity> that has the value Position<Value> for the custom field Position<CustomFieldName>. |
Description
The API provides all the instances in an entity that has a specific value for a custom field.
This can be used to search for records that has specified values for custom fields.
Events
API: CustomField.GetValue
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| Entity | FetchKey | Input | The entity the custom field is defined for. |
| InstanceKey | FetchKey | Input | The unique identification of the record in the entity (converted to a character string). |
| PropertyName | FetchKey | Input | The name of the custom field. |
| Value | FetchedData | Output | The specified value. |
Description
Retrieves the value for a custom field for a record. If no value has been registered for the custom field, the API returns a blank value.
Events
API: CustomField.SetValue
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| Entity | Input | Input | The entity the custom field is defined for. |
| InstanceKey | Input | Input | The unique identification of the record in the entity (converted to a character string). |
| PropertyName | Input | Input | The name of the custom field. |
| Value | Input | Input | The specified value. |
Description
Registers the value for the custom field.
Events
EvF139 - Error on set custom field value
EvF141 - Illegal entity
EvF142 - Illegal instance key
EvF143 - Custom field not defined
API: FolderListBlockFetchForSite
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| FolderListName | Position | Input | The name of the folder list. |
| FolderListSiteKey | Position | Input | The site the folder list is defined in. |
| RowsFetched | Control | Dual | The number of fetched records in the output variable FetchedData. |
| Position | Control | Input | Specifies whether the data in the Position variable is used for positioning when fetching the data. |
| FolderListID | FetchedData(64) | Output | The unique identification of the folder list. |
| FolderListText | FetchedData(64) | Output | A description of the folder list. |
| FolderListAuthLevel | FetchedData(64) | Output | Not used. |
| FolderListName | FetchedData(64) | Output | The name of the folder list - it is this field, which is shown for the identification of the folder list in the administration interface. The combination of FolderListName and FolderListSiteKey is unique. |
| FolderListSiteKey | FetchedData(64) | Output | Identifies the site, which the folder list is defined for . |
Description
This API behaves like a standard BlockFetch function. The data is restricted to the site specified by the input field FolderListSiteKey in the Position variable. The data will be shown in FolderListName order.
To make it easier to use this API function, a dummy view (WSYAPI/DataStructures.FolderLists.BySiteName) is provided. Use this view to replace in e.g. grid page functions.
Events
API: FolderListSingleFetch
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| FolderListID | FetchKey | Input | The unique identification of the folder list. |
| FolderListID | FetchedData | Output | The unique identification of the folder list. |
| FolderListText | FetchedData | Output | A description of the folder list. |
| FolderListAuthLevel | FetchedData | Output | No longer used. |
| FolderListName | FetchedData | Output | The name of the folder list - it is this field, which is shown for the identification of the folder list in the administration interface. The combination of FolderListName and FolderListSiteKey is unique. |
| FolderListSiteKey | FetchedData | Output | Identifies the site, which the folder list is defined for . |
Description
The function behaves as a standard SingleFetch function.
Events
API: FolderListSingleFetchSiteName
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| FolderListName | FetchKey | Input | The name of the folder list. |
| FolderListSiteKey | FetchKey | Input | Identifies the site, which the folder list is defined for . |
| FolderListID | FetchedData | Output | The unique idenification of the folder list. |
| FolderListText | FetchedData | Output | A description of the folder list. |
| FolderListAuthLevel | FetchedData | Output | No longer used. |
| FolderListName | FetchedData | Output | The name of the folder list - it is this field, which is shown for the identification of the folder list in the administration interface. The combination of FolderListName and FolderListSiteKey is unique. |
| FolderListSiteKey | FetchedData | Output | Identifies the site, which the folder list is defined for . |
Description
The function behaves as a standard SingleFetch function.
Events
API: GetBasicSessionData
Interface
| Field | Variable | Description |
|---|---|---|
| SessionSurrogate | Input | The identification of the current session. |
| SiteKey | Output | The identification of the current site. |
| StaticKeyUserPwdCrypt | Output | The value used when encrypting passwords (for future use). |
| DynamicKeyWebSign | Output | The key used for signing WebInput fields. |
| FolderListID | Output | The Folder List used to find the templates. |
| UserSurrogate | Output | The Identification of the current user. |
| MenuLinkSurrogate | Output | Surrogate for last activated menu item in the site structure. |
| SessionStatus | Output | The status of the session (Active, Inactive, or TooManyFailedLogins).. |
| HttpUrl | Output | The full URL to access the current site. |
| HttpsUrl | Output | The full URL to access the current site if using SSL. |
| FormAction | Output | The URL path used in FORM elements on the generated HTML pages. |
| IpAddress | Output | The IP address of the current session. |
| CreationDate | Output | The creation date of the session. |
| CreationTime | Output | The creation time of the session. |
| LastRequestDate | Output | The date of the last request for the session. |
| LastRequestTime | Output | The time of the last request for the session. |
| RequestCount | Output | The number of requests done by the current session. |
Description
Returns the session information and selected information from the current site.
This function is called in the initialize subroutine of all EventHandlerForProcess and PageGeneratorForProcess functions. If you need information about the current session in other parts of your application you can call this function. The information returned also includes an identification of the current site.
Events
EvF012 - Error reading session
EvF017 - Error reading site
API: GetEventInformation
Interface
| Field | Variable | Description |
|---|---|---|
| EventID | Input | The identification of the event (this information is returned by the function in the returned status field). |
| EventContent | Output | The text of the thrown event. |
| EventCategory | Output | Indicates the severity of the event. |
| EventTypeID | Output | The identification of the event type. |
| EventType | Output | A textual description of the event type. |
Description
Websydian Express functions can report a number of events. If a function has terminated because of an event it will return the EventID of this event in the *Returned status field.
Call this function to obtain further information about the event.
Events
API: GetEventTypeForEvent
Interface
| Field | Variable | Description |
|---|---|---|
| EventID | Input | The identification of the event (this information is returned by Websydian Express functions in the *Returned status field). |
| EventTypeID | Output | The identification of the event type. |
Description
Obtains the identification of the event type of an event instance.
Events
API: GetSessionData
Interface
| Field | Variable | Description |
|---|---|---|
| SessionSurrogate | Input | The identification of the current session. |
| SiteKey | Output | The identification of the current site. |
| FolderListID | Output | The folder list used to find the templates. |
| UserSurrogate | Output | The identification of the current user. |
| MenuLinkSgt | Output | Surrogate for last activated menu item in the site structure. |
| SessionStatus | Output | Indicates whether the session is active. |
| IpAddress | Output | The IP address of the current session. |
| CreationDate | Output | The creation date of the session. |
| CreationTime | Output | The creation time of the session. |
| LastRequestDate | Output | The date of the last request for the session. |
| LastRequestTime | Output | The time of the last request for the session. |
| RequestCount | Output | The number of requests done by the current session. |
Description
Fetch information for a session.
Events
EvF036 - Session not found
API: GetSiteData
Interface
| Field | Variable | Description |
|---|---|---|
| SiteKey | Input | The identification of the Site. |
| SiteDescription | Output | A textual description or name of the Site. |
| EntryURL | Output | The URL mapped to the Site. |
| DispatcherUnsafeLearningMode | Output | Indicates whether the site is currently accepting events, which hasn't previously been defined (value = Y) or whether no new events will be accepted (value = N). |
| StaticKeyUserPwdCrypt | Output | The value used when encrypting passwords |
| DynamicKeyWebSign | Output | The key used for signing webinput fields. |
| SessionTimeOut | Output | Timeout in minutes |
| HttpUrl | Output | The full URL to access the current site. |
| HttpsUrl | Output | The full URL to access the current site if using SSL. |
| FormAction | Output | The URL path used in FORM elements on the generated HTML pages. |
Description
Fetch information about a site.
Events
EvF017 - Error reading site
API: Presentation.DeletePresentationProperty
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| PresentationSurrogate | Input | Input | The unique identification of the presentation. This specifies the presentation that the property has been specified for. |
| PropertyName | Input | Input | The name of the property to delete. |
Description
This API can be used to delete a property for a presentation. Please note that this physically deletes the record.
Events
API: Presentation.GetPresentation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| PresentationSurrogate | FetchKey | Input | The unique identification of the presentation. This specifies the presentation to retrieve information for. |
| PresentationSurrogate | FetchedData | Output | The unique identification of the presentation. |
| PresentationSiteKey | FetchedData | Output | The identification of the site that the presentation belongs to. |
| TemplateSuffix | FetchedData | Output | The suffix used to specify that the HTML templates are belonging to the presentation. |
| TemplateOverrideName | FetchedData | Output | The override name specified for the presentation. |
| PresentationName | FetchedData | Output | The name of the presentation. |
| PresentationComment | FetchedData | Output | Any comments specified for the presentation |
| ProcessSurrogate | FetchedData | Output | The unique identification of the process that the presentation belongs to. |
| ProcessID | FetchedData | Output | The program name of the ProcessEntryPoint used by the process that the presentation belongs to. |
| ProcessType | FetchedData | Output | The type of the process that the presentation belongs to. The type can be either Business Process (literal value 4), Menu Loader (literal value 5), or Frameset Loader (literal value 6). |
| ProcessDescription | FetchedData | Output | The description specified for the process that the presentation belongs to |
| ProcessComment | FetchedData | Output | Any comments specified for the process that the presentation belongs to. |
| ProcessText | FetchedData | Output | The name of the process that the presentation belongs to. |
Description
This API can be used to retrieve data about any presentation by specifying a PresentationSurrogate (a unique identification of a Presentation). This API is mostly for future use as there are currently no available API's that return a presentation surrogate. If you want to retrieve information about the current presentation used by the session call the weebserver API GetCurrentPresentation.
Events
API: Presentation.GetPresentationProperty
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| PresentationSurrogate | Input | Input | The unique identification of the presentation. This specifies the presentation that the property has been specified for. |
| PropertyName | Input | Input | The name of the property. |
| Value | FetchedData | Output | The value specified for the property. |
Description
This API can be used to retrieve the value specified for a specific property specified for a presentation. The normal situation is that you want to retrieve a property for the pressentation currently being used by the session - use the webserver API GetCurrentPresentation to retrieve the PresentationSurrogate for this presentation.
Events
EvF021 - Presentation not found
API: Presentation.GetPropertiesForPresentation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| PresentationSurrogate | Position | Input | The unique identification of the presentation. This is used to restrict the retrieved data. |
| PropertyName | Position | Input | The name of the property. This is used to position the retrieved data. |
| Position | Control | Input | Specify whether the API should position based on the Position variable |
| RowsFetched | Control | Dual | Returns the number of rows returned for the Presentation |
| PresentationSurrogate | FetchedData (64) | Output | The unique identification of the presentation. |
| PropertyName | FetchedData (64) | Output | The name of the property |
| Value | FetchedData (64) | Output | The value specified for the property |
Description
This API is a blockfetch function that retrieves all the properties specified for a presentation (the presentation surrogate is used to restrict the data). The normal situation is that the properties should be retrieved for the current presentation for the session - use the webserver API GetCurrentPresentation to retrieve this surrogate.
Events
EvF021 - Presentation not found
API: Presentation.SetPresentationProperty
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| PresentationSurrogate | Input | Input | The unique identification of the presentation. This specifies the presentation that the property has been specified for. |
| PropertyName | Input | Input | The name of the property. |
| Value | Input | Input | The value specified for the property. |
Description
This API can be used to set the value for a specific property for a presentation. The normal situation is that you want to set a property for the pressentation currently being used by the session - use the webserver API GetCurrentPresentation to retrieve the PresentationSurrogate for this presentation.
Events
EvF021 - Presentation not found
EvF178 - Property Name is blank
API: Role.ClearIntranetOnly
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification for the role |
Description
Makes the role valid for use by sessions that does not originate inside the intranet.
Events
EvF100 - Role not found
API: Role.CreateRole
Interface
| Field | Variable | ...as | Description | |
|---|---|---|---|---|
| RoleName | InsertData | Input | The name of the role. This must be unique for the site (mandatory). | |
| RoleDescription | InsertData | Input | A textual description of the role (optional). | |
| RoleComment | InsertData | Input
|
Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. (optional) | |
| RoleSiteKey | InsertData | Input | The site which the role belongs to. (mandatory) | |
| RoleFolderListID | InsertData | Input | The folder list to be used for sessions authorized by this role. (mandatory) | |
| RoleSurrogate | Output | Output | The unique identification of the created role. If the validation or creation of the record fails, the returned RoleSurrogate will be 0. | |
| NumberOfErrors | Error | Output | The number of errors encountered and reported in the ErrorArray. | |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or create. |
Description
Validates and creates a role for a specific site.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The output field NumberOfErrors is set to the number of errors returned in ErrorArray.
Events
API: Role.DeleteRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification for the role. |
| NumberOfErrors | Error | Output | The number of errors encountered and reported in the ErrorArray. |
| ErrorMessage | ErrorArray (10) | Output | A description of an error, which has occurred during either validation or create. |
Description
Checks whether the role can be deleted - and deletes the role if it is allowed.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The output field NumberOfErrors is set to the number of errors returned in ErrorArray.
Roles that are assigned to users or site elements can't be deleted.
Note that the role is deleted from the database and can't be retrieved after a delete.
Events
API: Role.GetByName
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleName | Input | Input | The name of the role. |
| RoleSiteKey | Input | Input | The unique identification of the site. |
| RoleSurrogate | FetchedData | Output | The unique identification of the role. |
| RoleName | FetchedData | Output | The name of the role. This must be unique for the site. |
| RoleDescription | FetchedData | Output | A textual description of the role. |
| RoleComment | FetchedData | Output | Comment field for the role. |
| RolePriority | FetchedData | Output | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. |
| RoleSiteKey | FetchedData | Output | The site which the role belongs to. |
| RoleFolderListID | FetchedData | Output | The folder list to be used for sessions authorized by this role. |
Description
Retrieves the information for a role, based on the role name and the site the role belongs to.
Events
API: Role.GetRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | FetchKey | Input | The unique identification of the role. |
| RoleSurrogate | FetchedData | Output | The unique identification of the role. |
| RoleName | FetchedData | Output | The name of the role. This must be unique for the site. |
| RoleDescription | FetchedData | Output | A textual description of the role. |
| RoleComment | FetchedData | Output | Comment field for the role. |
| RolePriority | FetchedData | Output | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. |
| RoleSiteKey | FetchedData | Output | The site which the role belongs to. |
| RoleFolderListID | FetchedData | Output | The folder list to be used for sessions authorized by this role. |
Description
Retrieves the information for a role, based on the unique identification for the role.
Events
API: Role.GetRolesByName
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleName | Position | Input | The name of the role. Can be used to position the start of the list. |
| RoleSiteKey | Position | Input | Identifies the site the roles are to be fetched for (mandatory/restrict). |
| Position | Control | Input | Specifies whether the data in the Position variable is used for positioning when fetching the data. |
| RowsFetched | Control | Dual | The number of fetched records in the output variable FetchedData. |
| RoleSurrogate | FetchedData (64) | Output | The unique identification of the role. |
| RoleName | FetchedData (64) | Output | The name of the role. |
| RoleDescription | FetchedData (64) | Output | A textual description of the role. |
| RoleComment | FetchedData (64) | Output | Comment field for the role. |
| RolePriority | FetchedData (64) | Output | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. |
| RoleSiteKey | FetchedData (64) | Output | The site which the role belongs to. |
| RoleFolderListID | FetchedData (64) | Output | The folder list to be used for sessions authorized by this role. |
Description
Retrieves a list of the roles that has been defined for a site. The roles are retrieved in role name order.
Events
API: Role.IsRoleIntranetOnly
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification of the role. |
| IntranetOnly | Output | Output | Yes/No field, specifying whether the role only can be assigned to sessions originating inside the intranet (Yes). |
Description
Checks whether the role is specified for intranet use only.
Events
API: Role.RemoveAllSiteElements
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification of the role. |
Description
Removes the roles from all site elements. After calling this API, the role does not authorize any site elements. The API can be used in a situation where the role is to be deleted (as a role can't be deleted until all assignments to users and site elements are removed).
Events
EvF100 - Role not found
API: Role.RemoveAllUsers
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification of the role. |
Description
Removes the roles from all Users. After calling this API, no users will have this role. The API can be used in a situation where the role is to be deleted (as a role can't be deleted until all assignments to users and site elements are removed).
Events
EvF100 - Role not found
API: Role.SetIntranetOnly
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification of the role. |
Description
Specifies that the role may only be assigned to session that originate inside the intranet. When IntranetOnly is specified for a role, it will not be assigned to a session the originates outside the intranet, event though the role is assigned to the user.
Events
EvF100 - Role not found
API: Role.UpdateRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleName | UpdateData | Input | The name of the role. This must be unique for the site (mandatory). |
| RoleDescription | UpdateData | Input | A textual description of the role (optional). |
| RoleComment | UpdateData | Input | Comment field for the role (optional). |
| RolePriority | UpdateData | Input | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. (optional) |
| RoleSiteKey | UpdateData | Input | The site which the role belongs to. (mandatory) |
| RoleFolderListID | UpdateData | Input | The folder list to be used for sessions authorized by this role. (mandatory) |
| RoleSurrogate | UpdateKey | Input | The unique identification of the created role. (mandatory) |
| NumberOfErrors | Error | Output | The number of errors encountered and reported in the ErrorArray. |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or create. |
Description
Validates and updates an existing role.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The output field NumberOfErrors is set to the number of errors returned in ErrorArray.
Events
API: Role.ValidateDeleteRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification of the created role. (mandatory) |
| NumberOfErrors | Error | Output | The number of errors encountered and reported in the ErrorArray. |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or create. |
Description
Validates whether a role can be deleted.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The output field NumberOfErrors is set to the number of errors returned in ErrorArray.
Roles that are assigned to users or site elements can't be deleted.
Events
API: Role.ValidateRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Data | Input | The unique identification of the created role. Must be specified when ValidationType is update. |
| RoleName | Data | Input | The name of the role. This must be unique for the site. |
| RoleDescription | Data | Input | A textual description of the role. |
| RoleComment | Data | Input | Comment field for the role. |
| RolePriority | Data | Input | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. |
| RoleSiteKey | Data | Input | The site which the role belongs to. |
| RoleFolderListID | Data | Input | The folder list to be used for sessions authorized by this role. |
| ValidationType | Input | Input | Specifies whether the record should be validated for update or insert. |
| NumberOfErrors | Error | Output | The number of errors encountered and reported in the ErrorArray. |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or create. |
Description
Validates whether a role can be inserted or updated.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The output field NumberOfErrors is set to the number of errors returned in ErrorArray.
The validation can be called for either update or insert - specified by the input parameter ValidationType.
Events
API: Session.AddRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification of the site. |
| SessionSurrogate | Input | Input | The unique identification of the session. |
Description
Adds the role to the session. This extends the authorization of the session to include the site elements that is authorized by this role.
Events
EvF036 - Session not found
EvF100 - Role not found
EvF120 - Session and Role in different sites
API: Session.Create
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSiteKey | Data | Input | The identification of the site (mandatory). |
| SessionUserSurrogate | Data | Input | The unique identification of the user owning the session (optional). |
| IpAddress | Data | Input | The IP address of the machine where the request originates (the machine running the browser) (optional). |
| SessionSurrogate | Key | Output | The unique identification of the created session. |
| NumberOfErrors | Error | Output | The number of errors in ErrorArray. |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or create. |
Description
This API offers the developer the possibility to create a session outside the normal session creation done by Websydian Express.
The function starts by calling the SessionCreateValidation API (for detailed information about the validation - see the description of this API).
If the validation is successful, the *Returned status is set to *Successful, the session is created, and the generated identification of the session is returned in the Key output variable.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The output field NumberOfErrors is set to the number of errors returned in ErrorArray.
Events
API: Session.CreateValidation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSiteKey | Data | Input | The identification of the site (mandatory). |
| SessionUserSurrogate | Data | Input | The unique identification of the user owning the session (optional). |
| IpAddress | Data | Input | The IP address of the machine where the request originates (the machine running the browser) (optional). |
| NumberOfErrors | Error | Output | The number of errors returned in ErrorArray. |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or create. |
Description
This function performs the validation necessary to create a new session.
If the validation is successful *Returned status is set to *Successful.
If the validation fails *Returned status is set to a non-successful value and for each error an error message is written to the ErrorArray output variable. The output field NumberOfErrors is set to the number of errors returned in ErrorArray.
The following rules are enforced by the validation:
SessionSiteKey
This field is mandatory and must specify an existing site.
SessionUserSurrogate
This field is optional. If the field is specified the surrogate must identify an existing user for the site specified by the input field SessionSiteKey.
Events
API: Session.GetRoles
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Position | Input | The unique identification of the role. Used for positioning the start of the list. |
| SessionSurrogate | Position | Input | The unique identification of the session. (restrict) |
| Position | Control | Input | Specifies whether the data in the Position variable is used for positioning when fetching the data. |
| RowsFetched | Control | Dual | The number of fetched records in the output variable FetchedData. |
| RoleSurrogate | FetchedData (64) | Output | The unique identification of the role. |
| SessionSurrogate | FetchedData (64) | Output | The unique identification of the session. |
| RoleName | FetchedData (64) | Output | The name of the role. |
| RoleDescription | FetchedData (64) | Output | A textual description of the role. |
| RoleComment | FetchedData (64) | Output | Comment field for the role. |
| RolePriority | FetchedData (64) | Output | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. |
| RoleSiteKey | FetchedData (64) | Output | The site which the role belongs to. |
| RoleFolderListID | FetchedData (64) | Output | The folder list to be used for sessions authorized by this role. |
Description
Retrieves a list containing the roles assigned to the session.
Events
API: Session.IsAuthorizedForRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | CheckKey | Input | The unique identification of the role. |
| SessionSurrogate | CheckKey | Input | The unique identification of the session. |
Description
Check whether the session is authorized for the specified role. This can be used if you have functionality/content in your business process that depends on whether a specific role is assigned to the session.
Events
API: Session.RefreshFolderList
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSurrogate | Input | Input | The unique identification of the session. |
Description
Sets the folder list for the session based on the user and roles assigned to the session. Use this API to set the folder list after changing the roles or user for the session.
Events
EvF036 - Session not found
EvF122 - No roles specified for the session
API: Session.RemoveAllRoles
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSurrogate | Input | Input | The unique identification of the session. |
Description
Remove all roles from the session. Use this API if you want to clear the roles on a session before assigning new roles to a session.
Events
EvF036 - Session not found
API: Session.RemoveRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSurrogate | Input | Input | The unique identification of the session. |
| RoleSurrogate | Input | Input | The unique identification of the role. |
Description
Remove one role from the session. This means that the session will no longer have access to the site elements authorized by this role.
Events
EvF036 - Session not found
API: Session.SetAnonymousUserAndUpdate
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSurrogate | Input | Input | The unique identification of the session. |
Description
Reads the anonymous user registered for the site. Uses the roles and folder list assigned to this user to update the session.
Events
EvF017 - Error reading site
EvF030 - User not found (the user registered as anonymous user does not exist)
EvF036 - Session not found
EvF108 - No anonymous user for the session
EvF103 - No folder list found
EvF135 - User for session can't be updated (the session already have an assigned user).
API: Session.SetFolderList
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| FolderListID | Input | Input | The unique identification of the folder list. |
| SessionSurrogate | Input | Input | The unique identification of the session. |
Description
Updates the session with the specified folder list. The folder list is updated no matter which folder list is defined for the current user or roles assigned to the session.
Events
EvF036 - Session not found
EvF105 - Folder list not found
EvF123 - Folder list and session in different sites
API: Session.SetUserAndUpdate
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSurrogate | Input | Input | The unique identification of the session. |
| UserSurrogate | Input | Input | The unique identification of the user. |
Description
Updates the session with roles and folder list based on the user information.
Events
EvF017 - Error reading site
EvF030 - User not found (the user registered as anonymous user does not exist)
EvF036 - Session not found
EvF108 - No anonymous user for the session
EvF103 - No folder list found
EvF135 - User for session can't be updated (the session already have an assigned user).
API: Session.Update
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSurrogate | Data | Input | The unique identification of the session to update (mandatory). |
| SessionSiteKey | Data | Input | The identification of the site (mandatory). |
| SessionUserSurrogate | Data | Input | The unique identification of the user owning the session (optional). |
| IpAddress | Data | Input | The IP address of the machine where the request originates (the machine running the browser) (optional). |
| SessionStatus | Data | Input | The new status of the session (mandatory). Valid values: Active (A), TimedOut (T), Ended (E). |
| RefreshRolesAndFolderList | Data | Input | Set this parameter to Yes (Y) if you want to update the roles and
the folder list for the session based on the updated values. An example could this could be if you assign a user to the session - and set the parameter to yes, in this case you would get the roles and folder list based on the user settings. |
| NumberOfErrors | Error | Output | The number of errors in ErrorArray. |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or update. |
Description
This API offers the developer the possibility to update a session.
The function starts by calling the Session.UpdateValidation API (for detailed information about the validation see the description of this API).
If the validation is successful, the *Returned status is set to *Successful and the session is updated with the values specified in the input.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The field NumberOfErrors will contain the number of errors written to ErrorArray.
Events
API: Session.UpdateValidation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| SessionSurrogate | Data | Input | The unique identification of the session to update (mandatory). |
| SessionSiteKey | Data | Input | The identification of the site (mandatory). |
| SessionUserSurrogate | Data | Input | The unique identification of the user owning the session (optional). |
| IpAddress | Data | Input | The IP address of the machine where the request originates (the machine running the browser) (optional). |
| SessionStatus | Data | Input | The new status of the session (mandatory). Valid values: Active (A), TimedOut (T), Ended (E). |
| NumberOfErrors | Error | Output | The number of errors in ErrorArray. |
| ErrorMessage | ErrorArray(20) | Output | A description of an error, which has occurred during either validation or update. |
Description
This function performs the validation necessary to update a session.
If the validation is successful, the *Returned status is set to *Successful.
If the validation fails the *Returned status is set to a non-successful value and for each error an error message can be written in the ErrorArray output variable. The field NumberOfErrors is set to the number of errors written to ErrorArray.
The following rules are enforced by the validation:
SessionSurrogate
This field is mandatory and must specify a valid session to update. The session must be Active (SessionStatus set to Active).
SessionSiteKey
This field is mandatory and must specify an existing site.
SessionUserSurrogate
This field is optional. If the field is specified, it must specify an existing user for the site specified by the input field SessionSiteKey.
SessionStatus
The status the session is to be changed to. Valid values are "Active", "Ended", "TimedOut".
Events
API: User.AddRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | Input | Input | The unique identification of the role. |
| UserSurrogate | Input | Input | The unique identification of the user. |
Description
Assigns the role to the user.
Events
EvF030 - User not found
EvF100 - Role not found
EvF121 - User and role in different sites
API: User.BlockFetchByLogin
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| LoginName | Position | Input | Login name for a user. Used to position the search for users. Only users
with a login name positioned after than the one specified will be returned
in the output. A blank login name will return all users. |
| UserSiteKey | Position | Input | The identification of the current site. Restricts the output to users for a specific site. The site must be specified in the input, or no records will be returned. |
| Position | Control | Input | Specifies whether the values specified for LoginName and SiteKey is
to be used, or whether the output should start from the last record found
in the last search. Values: Yes (Y) or No (N). |
| RowsFetched | Control | Dual | The number of rows fetched in the search. |
| UserFolderListID | Limit | Input | Limits the search. Only records with the exact value specified for the UserFolderListID will be returned. |
| CrtByUserSgt | Limit | Input | Limits the search. Only records with the exact value specified for the CrtByUserSgt will be returned. |
| EmailAddress | Limit | Input | Limits the search. Only records with the exact value specified for the EmailAddress will be returned. |
| UserStatus | Limit | Input | Limits the search. Only records with the exact value specified for the
UserStatus will be returned. Values: Active (A), Inactive (I), TooManyFialedLogins(F) |
| UserSurrogate | FetchedData(64) | Output | The unique identification of the user. |
| UserSiteKey | FetchedData(64) | Output | The site the user belongs to. |
| LoginName | FetchedData(64) | Output | The login name of the user. |
| UserFolderListID | FetchedData(64) | Output | The folder list assigned to the user. |
| CrtByUserSgt | FetchedData(64) | Output | A reference to the user who created this user. |
| EmailAddress | FetchedData(64) | Output | The e-mail address of the user. |
| FullName | FetchedData(64) | Output | The full name of the user. |
| CreatedTime | FetchedData(64) | Output | Time of user creation. |
| CreatedDate | FetchedData(64) | Output | Date of user creation. |
| UserLanguageCode | FetchedData(64) | Output | For future use |
| Password | FetchedData(64) | Output | Signature of the user password |
| FailedLogins | FetchedData(64) | Output | The number of failed logins. |
| UserStatus | FetchedData(64) | Output | Values: Active (A), Inactive (I), TooManyFailedLogins(F) |
| LastLogin | FetchedData(64) | Output | Time stamp of the last time the user has logged in. |
Description
This is a standard BlockFetch function based on the user entity, with some extra possibilities to limit the search.
The API should be used if you at any time must have a list of users in your application.
To make it easier to use this function, a dummy view (WSYAPI/DataStructures.User.SiteKeyLogin) is provided. Use this view to replace in e.g. grid page functions.
Events
API: User.Delete
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Data | Input | The unique identification of the user to delete. |
| ErrorMessage | Error | Output | Text describing the reason if an error has occurred. |
Description
The API deletes the specified user from the database (physically removes the record). Before deleting the record, the API User.DeleteValidation is called. If the validation fails the *Returned status is set to a non-successful value and a text describing the error is returned in the ErrorMessage field.
If the validation is successful, the user specified by the surrogate is deleted.
Events
API: User.DeleteValidation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Data | Input | The unique identification of the user to delete. |
| ErrorMessage | Error | Output | Text describing the reason if an error has occurred. |
Description
Validates whether a user specified by UserSurrogate can be deleted. In addition to checking the existence of the user it is also checked whether the user is registered as a creating user on other users.
If the validation fails the *Returned status is set to a non-successful value and a text describing the error is returned in the ErrorMessage field.
Events
API: User.GetAuthorizedRolesByName
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleName | Position | Input | The role name used for positioning. |
| UserSurrogate | Position | Input | The unique identification of the user. (restrict) |
| Position | Control | Input | Specifies whether the data in the Position variable is used for positioning when fetching the data. |
| RowsFetched | Control | Dual | The number of fetched records in the output variable FetchedData. |
| UserSurrogate | FetchedData (64) | Output | The unique identification of the user. |
| RoleSurrogate | FetchedData (64) | Output | The unique identification of the role. |
| RoleName | FetchedData (64) | Output | The name of the role. |
| RoleDescription | FetchedData (64) | Output | A textual description of the role. |
| RoleComment | FetchedData (64) | Output | Comment field for the role. |
| RolePriority | FetchedData (64) | Output | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. |
| RoleSiteKey | FetchedData (64) | Output | The site which the role belongs to. |
| RoleFolderListID | FetchedData (64) | Output | The folder list to be used for sessions authorized by this role. |
Description
Retrieves a list containing the roles assigned to the user. The roles are sorted in role name order.
Events
API: User.GetAuthorizedRolesByPriority
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RolePriority | Position | Input | The role priority used for positioning. |
| UserSurrogate | Position | Input | The unique identification of the user. (restrict) |
| Position | Control | Input | Specifies whether the data in the Position variable is used for positioning when fetching the data. |
| RowsFetched | Control | Dual | The number of fetched records in the output variable FetchedData. |
| UserSurrogate | FetchedData (64) | Output | The unique identification of the user. |
| RoleSurrogate | FetchedData (64) | Output | The unique identification of the role. |
| RoleName | FetchedData (64) | Output | The name of the role. |
| RoleDescription | FetchedData (64) | Output | A textual description of the role. |
| RoleComment | FetchedData (64) | Output | Comment field for the role. |
| RolePriority | FetchedData (64) | Output | Numeric field - indicates the "importance" of the role. Used for situations where a session is authorized by more than one role and a choice between the roles are necessary. The higher the number, the more important the role is. |
| RoleSiteKey | FetchedData (64) | Output | The site which the role belongs to. |
| RoleFolderListID | FetchedData (64) | Output | The folder list to be used for sessions authorized by this role. |
Description
Retrieves a list containing the roles assigned to the user. The roles are sorted in descending role priority order (retrieves the most "important" roles first).
Events
API: User.IncrementFailedLogins
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Input | Input | The unique identification of the user. |
Description
Adds one to the current number of failed logins registered for the user.
Events
API: User.IsAuthorizedForRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| RoleSurrogate | CheckKey | Input | The unique identification of the role. |
| UserSurrogate | CheckKey | Input | The unique identification of the user. |
Description
Check whether the user is authorized for the role.
Events
API: User.RemoveAllRoles
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Input | Input | The unique identification of the user. |
Description
Remove all roles for the user - this means that the user will not be able to access the site. Normally this API will be used when the user is to be deleted (as a user can't be deleted as long as he has roles assigned).
Events
EvF030 - User not found
API: User.RemoveRole
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Input | Input | The unique identification of the user. |
| RoleSurrogate | Input | Input | The unique identification of the role. |
Description
Remove one specific role from the user.
Events
EvF030 - User not found
EvF100 - Role not found
API: User.ResetFailedLogins
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Input | Input | The unique identification of the user. |
Description
Sets the number of failed logins for the user to zero.
Events
API: User.SingleFetch
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Input | Input | The unique identification for a user. Can be obtained from the session information (e.g. by calling the API GetBasicSessionData). |
| UserAuthLevel | FetchedData | Output | Not used. |
| UserFolderListID | FetchedData | Output | If the user has assigned a specific folder list the identification is returned in this field. |
| CrtByUserSurrogate | FetchedData | Output | The unique identification of the user who have created the current user. Use the API UserSingleFetch to obtain more information about the creating user. |
| EmailAddress | FetchedData | Output | The email address registered for the user. |
| LoginName | FetchedData | Output | The login name used by the user (unique for the site). |
| FullName | FetchedData | Output | The name registered for the user. |
| ErpCustomerKey | FetchedData | Output | For future use. |
| ErpAccountKey | FetchedData | Output | For future use. |
| CreatedTime | FetchedData | Output | User creation time. |
| CreatedDate | FetchedData | Output | User creation date. |
| UserLanguageCode | FetchedData | Output | For future use. |
| UserSiteKey | FetchedData | Output | Identifies the site, which the user is registered for. |
| UserSurrogate | FetchedData | Output | The unique identification of the user (same as input). |
| Password | FetchedData | Output | The signed value of the user password. Can be used to compare the password with a signature of a user entered value. |
| FailedLogins | FetchedData | Output | Shows the number of failed logins performed by the user. |
| UserStatus | FetchedData | Output | The status of the user. Valid values are: Active (A), Inactive (I), TooManyFailedLogins(F). |
| LastLogin | FetchedData | Output | Timestamp for last login by user. |
Description
The API gives you the possibility to obtain information about a specific user.
Events
API: User.SingleFetchSiteLogin
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| LoginName | FetchKey | Input | The login name defined for the user |
| UserSitekey | FetchKey | Input | The site the user belongs to. The combination of the login name and the site is unique. |
| UserAuthLevel | FetchedData | Output | Not used. |
| UserFolderListID | FetchedData | Output | If the user has assigned a specific folder list the identification is returned in this field. |
| CrtByUserSgt | FetchedData | Output | The unique identification of the user who has created the current user. Use the API UserSingleFetch to obtain more information about the creating user. |
| EmailAddress | FetchedData | Output | The email address registered for the user. |
| LoginName | FetchedData | Output | The login name used by the user (same as input). |
| FullName | FetchedData | Output | The name registered for the user. |
| ErpCustomerKey | FetchedData | Output | For future use. |
| ErpAccountKey | FetchedData | Output | For future use. |
| CreatedTime | FetchedData | Output | User creation time. |
| CreatedDate | FetchedData | Output | User creation date. |
| UserLanguageCode | FetchedData | Output | For future use. |
| UserSiteKey | FetchedData | Output | Identifies the site, which the user is registered for (same as input). |
| UserSurrogate | FetchedData | Output | The unique identification of the user (same as input). |
| Password | FetchedData | Output | The signed value of the user password. Can be used to compare the password with a signature of a user entered value. |
| FailedLogins | FetchedData | Output | Shows the number of failed logins performed by the user. |
| UserStatus | FetchedData | Output | The status of the user. Valid values are: Active (A), Inactive (I), TooManyFailedLogins(F). |
| LastLogin | FetchedData | Output | Timestamp for last login by user. |
Description
The API can be used to find information about a user, when the user surrogate is not known. This API finds the user based on the login name and the site the user belongs to.
The API behaves as a standard SingleFetch function.
Events
API: User.StateChange
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Data | Input | The unique identification for a user. |
| UserStatus | Data | Input | The new status for the user. Valid values are: Active (A), Inactive (I), TooManyFailedLogins (F). |
| ErrorMessage | Error | Output | If an error occurs this field can contain a text describing the error. |
Description
The API offers the possibility to change the state of the user without having to consider any other values for the user (e.g. reactivate a user, who has been deactivated because of too many failed login attempts).
The API calls the API UserStateChangeValidation before doing the update.
If an error occurs, a text describing the error is written to the ErrorMessage output field.
Events
API: User.StateChangeValidation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Data | Input | The unique identification for a user. |
| UserStatus | Data | Input | The new status for the user. Valid values are: Active (A), Inactive (I), TooManyFailedLogins (F). |
| ErrorMessage | Error | Output | If an error occurs this field can contain a text describing the error. |
Description
The API performs the necessary validation for an update of the state of the user.
The UserSurrogate has to identify an existing user and the UserStatus must be one of the valid values for the field.
If an error occurs, a text describing the error is written to the ErrorMessage output field.
Events
API: User.Update
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate. | Input | Input | The unique identification for a user (mandatory). |
| UserFolderListID | Input | Input | The identification of the folder list to be assigned to the user (optional). |
| EmailAddress | Input | Input | The e-mail address to be assigned to the user (mandatory). |
| LoginName | Input | Input | The identification the user must use when logging in to the site. The login name must be unique for the site (mandatory). |
| FullName | Input | Input | The name of the user (mandatory). |
| UserSitekey | Input | Input | The site the user is defined for (mandatory). |
| UserStatus | Input | Input | The status the user will be assigned. Valid values are: Active (A), Inactive (I), TooManyFailedLogins (F) (Mandatory). |
| NumberOfErrors | Error | Output | The number of messages in the ErrorArray output variable. |
| ErrrorMessage | ErrorArray(20) | Output | For each error a text describing the error is written to the output variable ErrorArray. |
Description
The API offers the possibility to update values for an existing user. Before doing the update the API User.UpdateValidation is called.
If the validation fails a non-successful value is written to *Returned status and a message can is written to ErrorArray. If the validation is successful the *Returned status is set to *Successful and the update is done.
Please note that if you want to update the password for a user you will have to use the web server API PasswordUpdate.
If you just want to update the state of the user you can use the server API UserStateChange instead.
Please note that if you do not specify a value for the folder list (UserFolderListID), the user's session will have a folder list assigned based on the roles assigned to the user. This means that unless you want to override this behavior, you should just leave this input field blank.
Events
API: User.UpdateValidation
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Data | Input | The unique identification for a user (mandatory). |
| UserFolderListID | Data | Input | The identification of the folder list to be assigned to the user (optional). |
| EmailAddress | Data | Input | The e-mail address to be assigned to the user (mandatory). |
| LoginName | Data | Input | The identification the user must use when logging in to the site. The login name must be unique for the site (mandatory). |
| FullName | Input | Input | The name of the user (mandatory). |
| UserSitekey | Input | Input | The site the user is defined for (mandatory). |
| UserStatus | Input | Input | The status assigned to the user. Valid values are: Active (A), Inactive (I), TooManyFailedLogins (F) (Mandatory). |
| NumberOfErrors | Error | Output | The number of messages in the ErrorArray variable. |
| ErrrorMessage | ErrorArray(20) | Output | For each error a text describing the error can be written to the output variable ErrorArray (occurs 20). |
Description
Performs the validation that is necessary before an update of an existing user can be performed.
If the validation fails a non-successful value is written to *Returned status and a message is written to the ErrorArray output variable. If the validation is successful the *Returned status is set to *Successful and the update is done.
The following validation is performed:
UserSurrogate
The surrogate must identify an existing user to be updated.
UserFolderListID
This field is optional. If specified, the ID must identify an existing folder list.
EmailAddress
Mandatory.
LoginName
This field is mandatory. The combination of login name and site must be unique.
FullName
Mandatory.
UserSitekey
This field is mandatory and must identify an existing site
UserStatus
This field is mandatory and must be one of the valid values defined for the field.