The ARCOS Application Programming Interface ("API") is a Representational State Transfer ("REST") style interface that allows clients to use Hyper Text Transfer Protocol ("HTTP") methods to perform data procedures in the ARCOS platform without the need for the traditional web application.
Click the link below for the latest ARCOS Web Services documentation:
ARCOS API Platform Integration Manual
*Note: Not all companies have all of the items described in the Online Help.
*Please note, the ARCOS online documentation is a living document that is always under review. If you see information that is inconsistent with the behavior in the application, or you do not see a page covering an ARCOS feature you would like to know more about, please contact the ARCOS Support Center.
For your convenience, the documentation is also available here on the portal. See below.
Navigation
Appendix Continued, Definitions
ARCOS Method Endpoint Examples. 13
Method Categories and Types. 18
getRestConfigXml - GET /application/wadl 18
getXsd - GET /application/wadl/xsd0.xsd. 18
subscribeForPush - GET /subscriptions. 26
cancelSubscription - DELETE /subscriptions. 26
searchEmployees - GET /employees. 29
getEmployee - GET /employees/{contactId} 30
createEmployee - POST /employees. 30
createEmployees - POST /employees/batch. 32
updateEmployee - PUT /employees. 33
getExtendedAttributes – GET /employees/extendedAttributes. 34
getExtendedAttributeValues - GET /employees/attributeValues. 35
getEmployeeStub – GET /employees/stubs/{contactId} 36
getEmployeeStubs – GET /employees/stubs. 37
getEmployeeWorkingStatus - GET /employees/workingStatus/{contactId} 38
runRosterRules - POST /employees/runRosterRules. 38
getSafetyNoticeDetails - GET /employees/getResponse. 38
saveEmployeeSafety - POST /employees/saveEmployeeSafety. 38
Sorting Records in the Scheduler 44
Employee Schedule Selectors. 45
Displaying by Primary Class. 46
Displaying by Checked Only. 46
Applying Shifts via ShiftAssign Roster Preference. 48
getRecords - GET /schedules/records. 50
getShiftsAssignments - GET /schedules/shifts. 51
getEmployeeSchedules - GET /schedules/employeeSchedules. 52
Sync - GET /schedules/sync. 52
getScheduleRecord - GET /schedules/{memexId} 55
createRecords - POST /schedules/records. 55
createShift - POST /shifts. 56
updateRecord - PUT /schedules/records/{memexId} 57
updateRecords - PUT /schedules/records. 57
deleteRecord - DELETE /schedules/records/{memexId} 58
getScheduleRequests - GET /schedules/scheduleRequests. 58
getScheduleRequest - GET /schedules/scheduleRequest/{schedRequestId} 58
© 2022 ARCOS LLC – All rights reserved. All trademarks mentioned in this document belong to ARCOS or their respective owners. Confidential & Proprietary.
Background
Technology
The ARCOS Application Programming Interface (“API”) is a Representational State Transfer (“REST”) style interface that allows clients to use Hyper Text Transfer Protocol (“HTTP”) methods to perform data procedures in ARCOS without the need for the traditional web application.
Common command line tools such as cURL(https://en.wikipedia.org/wiki/CURL) can be used to interact with the ARCOS API and perform any of the operations listed in this document.
The Web Application Description language (“WADL”) for the ARCOS API can be viewed by visiting https://qa.rostermonster.com/arcos/rest/application/wadl while authenticated in ARCOS or appropriately authenticated on a GET method call. The WADL contains a listing of the various methods that have been exposed to your instance.
For a complete XML schema reference (“XSD”), please consult the following resource: https://qa.rostermonster.com/arcos/rest/application/wadl/xsd0.xsd
Purpose
The purpose of the ARCOS API is to allow users and organizations access to manage their data programmatically. For example, many customers choose to utilize the API for synchronizing employee data from an existing Human Resources system. A brief selection of some use cases for the ARCOS API would include:
- Seamlessly on-board employees by loading them to ARCOS as they appear in your HR system.
- Automatically create Callouts based on outage activity in an Outage Management System (“OMS”).
- Extract ARCOS Crew Manager data to perform data analytics and enable enhanced enterprise reporting with tools such as Microsoft PowerBI.
- Synchronize employee schedule data such as shifts and any variances in those shifts between your existing scheduling solutions and ARCOS.
- And many more…
Typical Usage
The API endpoints are all located at the base URL “https://rostermonster.com/arcos/rest” appropriate for a given environment, so the base URL of the QA environment API would be “https://qa.rostermonster.com/arcos/rest”. All endpoints have a relative path that is appended to the base URL to define the actual URL of the endpoint (for example “https://qa.rostermonster.com/arcos/rest/crews”).
This document will use the following format when describing any action performed against the API:
Method /Endpoint URL
Where Method is one of the standard HTTP Methods - GET, POST, PUT, DELETE and Endpoint URL is the path of the endpoint that should be acted upon - /cm/crews, /schedules, /loader, etc. The full path of the actual request would contain the host and application path as well (https://qa.rostermonster.com/arcos/rest/), but we will leave those out for the sake of brevity.
So, the command to obtain a collection of crews would be presented in this document as:
GET /cm/crews
while the actual URL into the API would look more like this:
GET https://qa.rostermonster.com/arcos/rest/cm/crews.
Many endpoints will provide the ability to work with a specific object instance by specifying the id of the object explicitly. To obtain the Crew with an ID of 1007 for example, you would execute:
GET /crews/1007
License
ARCOS currently offers two Integrations Licenses, Basic and Enterprise, as described below.
Basic
The Basic Platform API License grants ARCOS Customers the following integration abilities:
- Access to the ARCOS Platform API specifications and authorization methods. Generally, access to the API.
- Access to the ARCOS Platform Loader and all associated functionality, includes loading:
- Employee Data, including Extended Attributes
- Schedule Event Data (SDI flat-file 15-day exclusive periods only)
- Overtime Data
- Crew Manager Work Order Data
- Crew Manager Resource Data
- Crew Manager Lodging Data
- Access to the ARCOS Platform Extracts. This is typically for legacy reports that used to be dropped onto sFTP sites. Engineering may choose to support and develop new extracts available only via API as needed. By default, new customers will not have any Extracts available but will have access to the Extract methods.
- Access to the ARCOS Platform Employee Data. Basic customers have two options for managing employee data, loading data via the Loader and loading or extracting employee data directly from the employee's endpoint methods.
- Finally, the Basic API includes several Metadata endpoints for gathering information needed to support other API calls such as Contact IDs, Event IDs, Classification IDs, and Location IDs.
Enterprise
The Enterprise Platform API License grants ARCOS Customers, in addition to Basic API, the following integration abilities:
- Access to the ARCOS Platform Callout Data
- Summarized and Detailed Callout data is available for any callout(s) in the Platform
- Customers can generate new Callout’s via the API
- Callouts can be initiated via API, no need to login to the ARCOS Platform
- Access to sMART API Functionality
- Access to Crew Manager API Functionality
- The ability to run audit reports and other reporting functionality
- Manage Lodging
- Manage Crew Makeup
- Manage Resource Types and Resources
- Manage Attributes at all Resource Levels (Employee, Resource, Lodging, Crew)
- Access to Resource Assist API Functionality
- The ability to Extract, Import, and Delete RA Documents
- Access to Incident Manager API Functionality
- Manage Events, Teams, Processes, Process Teams, Categories, Locations, Scenarios, Functions, Levels, Role Types, Role Assignments, Event Wrappers, Storm Codes, Event Categories, Nodes, States, Role Requests, Exceptions, Phases, Documents, Log Entries, Settings, and Associated Callouts.
- Access to Platform Schedule API Functionality
- The ability to Extract, Load and Modify both Shifts and Schedules across the ARCOS platform.
HTTP Functionality
HTTP Request Methods
HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Although they can also be nouns, these request methods are sometimes referred to as HTTP verbs. Each of them implements a different semantic, but some common features are shared by a group of them: e.g. a request method can be safe, idempotent, or cacheable. Listed below are the methods supported by the ARCOS API. Source and backlinks: MDN Web Docs.
The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.
The POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server.
The PUT method replaces all current representations of the target resource with the request payload.
The DELETE method deletes the specified resource.
The PATCH method is used to apply partial modifications to a resource.
| Specification | Title | Comment |
| RFC 7231, section 4: Request methods | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content | Specifies GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE. |
| RFC 5789, section 2: Patch method | PATCH Method for HTTP | Specifies PATCH. |
ARCOS Method Endpoint Examples
All examples shown are for the QA environment. To switch examples to Production, the base host changes from qa.rostermonster.com to prod.rostermonster.com and the API Access Key is updated as needed. The Access Key is obtained within ARCOS on the Sys Admin > Rest Config page. All calls for both QA and PROD are performed via the HTTPS protocol. Any call examples provided are in the form of cURL shell commands.
The Request Body for most documented calls may be issued in JSON or XML format. The Response Body typically may be returned in either JSON or XML format. To switch the formatting of the Response Body, pass the appropriate Accept Header. Valid Accept headers for most endpoints in this document are as follows:
- Accept: application/json
- Accept: application/xml
- Accept: */*
Any exceptions to the above statements will be noted where they apply.
Endpoints are unique URLs that represents a resource ARCOS has made available to the client. Below are some examples.
Employee: https://qa.rostermonster.com/arcos/rest/employees
Schedule: https://qa.rostermonster.com/arcos/rest/schedules/records
Crew: https://qa.rostermonster.com/arcos/rest/cm/crews
Endpoints may be further qualified by adding query string or path parameters as described further in this section. Below are some examples.
Query String: https://qa.rostermonster.com/arcos/rest/employees?searchType=firstName&searchString=Joe
Path: https://qa.rostermonster.com/arcos/rest/cm/crews/2132
For simplicity, the remainder of this document will exclude the base URL, qa/prod.rostermonster.com, and the endpoint path part that consistently remains the same, /arcos/rest, when displaying supported operations. All Provided supported operations will be documented like the following example:
Documented Operation Path: getRestConfigXml – GET /application/wadl
Complete Operation Path: getRestConfigXml
– GET https://qa.rostermonster.com/arcos/rest/application/wadl
Note the PATH difference; The full operation URL must be considered even where not further specified in this document.
API Response Status Codes
Every API call returns a single, standard HTTP status code that indicate the overall status of the transaction. Some common codes include the following:
200 OK
The request has succeeded. Data errors may still exist within the transaction, but the client and server are communicating and understanding each other.
201 Created
The POST succeeded. Data was added or changed as requested.
400 Bad Request
The request could not be understood by the server due to malformed syntax. Usually indicates something is wrong with the clients request formatting or method.
401 Unauthorized
The request requires user authentication. The client was not properly authenticated to the server. ARCOS supports Basic and Bearer Token authorization. See the Authentication section for additional detail.
404 Not Found
The server has not found anything matching the Request-URI. Usually, the clients request URL is invalid and the requested resource does not exist in the ARCOS API.
405 Method Not Allowed
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. This may indicate a valid ARCOS resource that the clients enterprise is not licensed to use. Speak to your ARCOS representative with any questions on this error.
500 Internal Server Error
The server encountered an unexpected condition which prevented it from fulfilling the request. Usually indicates something is wrong with the server or an unsupported operation is being performed on a valid resource.
Query Parameters
GET requests for endpoints may return hundreds or thousands of a given object type. Most URLs will be limited to returning some variable number of elements per time-period (1000 schedule records per hour for example). To help narrow the results, endpoints may have required or optional query parameters. These parameters can be provided by appending a query string, consisting of the “?” symbol and any number of “key=value” pairs separated by the “&” symbol, to the end of the endpoint URL.
For example, to obtain a collection of scheduled shifts between January 1, 2016, and March 31st, 2016, you would execute the command:
GET /scheduledShifts?startTime=2016-01-01&endTime=2016-03-31
The query string is in italics.
Please refer to the specific endpoint’s documentation for a complete listing of its required and optional query parameters.
Path Parameters
In addition to Query Parameters, many endpoints will support some limited Path Parameters as well. These parameters are inputted directly into the url in place of the parameter name presented, using the format {parameterName}. For example, the {crewId} Path Parameter in the following URL:
/cm/crews/{crewId}
would be replaced by the actual crewId you want to search for.
Authentication
All actions performed against the API must be authenticated. Token Authentication and standard HTTP Basic Authentication are supported.
HTTP Basic Authentication
Basic authorization is provided the Authorization header of the Request. The Header is “Authorization” while the value content is “Basic […].” […] represents your company schema, which is the short code you enter into the rostermonster.com URL when using the Web GUI, and your Access Key provided on the Sys Admin > REST Config page of the Web Application all encoded in Base64.
Above: Location of the API Access Key in the ARCOS Web Application.
Example:
Authorization: Basic Base64Encoded(COMPANY:AccessKey)
Example presented programmatically as:
“Authorization” : “Basic Q09NUEFOWTpBY2Nlc3NLZXk=”
Token Authentication
Clients may use their API Access Key, available to System Administrators in Sys Admin > REST Config (See Figure above) within the Web Application, to obtain an Access Key that can be paired with their company schema and used to generate four (4) hour time limited authentication tokens to be used in future API calls.
To obtain an Access Token, issue a GET command and include your company name and accessToken as Query Parameters:
getToken - GET /auth?company=YourCompany&accessToken=accessKey
The company name, demonstrated as “YourCompany,” is your Schema ID you use when navigating to the Web UI. Example: http://auss.rostermonster.com = AUSS.
The Access Token, demonstrated as “accessKey,” is obtained from the ARCOS Platform Web UI, Sys Admin > REST Config tab.
Additionally, a POST method is also available allowing the user to supply the company and accessToken as part of a Multipart request payload:
postToken - POST /auth
Include a Multipart form with company and accessToken populated as described above in the getToken method.
The Response from ARCOS will contain an encoded Access Token to be used in future API Requests. The Access Token should be set in the Authorization Header of the Http Request as follows:
“Authorization” : “Bearer [AccessTokenProvidedByArcos]”
The Access Token may also be set in the Authorization Header of the Http Request as follows:
“Authorization” : “Token [AccessTokenProvidedByArcos]”
OR “Authorization” : “[AccessTokenProvidedByArcos]”
The Access Token will be valid for four (4) hours. Attempts to use an expired token will result in an HTTP return status of 401: Unauthorized.
API clients can obtain an updated token at any time but should probably do so before the 4-hour window has elapsed to ensure operations are handled appropriately.
Method Categories and Types
The following sections provide information about how to use each of the methods available in the API.
Each section will start with a brief description that explains how the method is used and is followed by a listing of the structures involved in any of the method supported operations.
Each of the supported operations will be presented with the HTTP Method to invoke and the URL to access for the operation. A table explaining the potential parameters for an operation will be given as well.
Some method sections present example calls to help illustrate potential use cases.
Application Data
Supported Operations
getRestConfigXml - GET /application/wadl
The Web Application Description Language (WADL) provides the ARCOS data format specification for use in building programmatic interfaces. The WADL Presented is unique based on the customer environment configuration. All licensed and configured methods will be provided in the WADL dynamically.
Response Payload
XML collection of the available API methods as documented throughout this manual.
getXsd - GET /application/wadl/xsd0.xsd
XSD (XML Schema Definition) is a World Wide Web Consortium (W3C) recommendation that specifies how to formally describe the elements in an Extensible Markup Language (XML) document. This operation provides a copy of all ARCOS Elements (“Data Structures”).
Response Payload
XML collection of ARCOS Data Structures. These Data Structures are also available in the Appendix – XSD section of this document.
Loader Data
The Loader Data Endpoint provides services to interact with the ARCOS file Loader. All existing loader file types are fully supported by the API. Typically, file loads are limited to specific times of day.
Please contact an ARCOS representative to determine the valid file loading times for your company.
Loader file specifications can be found in the Appendix – Flat File Specifications section of this document. Loader data structures can be found in the Appendix – XSD section of this document.
Supported Operations
getResults – GET /loader/results
Returns a collection of load results for loads that occurred between startDate and endDate. If no startDate/endDate is provided, then returns results for any loads that occurred in the past one (1) year.
Request Query Parameters
| Parameter | Type | Required | Default | Description |
| startDate | Datetime | no | Now - 365 Days | |
| endDate | Datetime | no | Now |
getLoadSummary - GET /loader/results/{loadId}
Returns a collection of the load results for the matching {loadId}. If the loadId is not provided then returns results for any loads that occurred in the past one (1) year.
Request Query Parameters
| Parameter | Type | Required | Default | Description |
| loadId | Int | yes | Now - 365 Days |
getLoadDetail - GET /loader/results/{loadId}/details
Returns a collection of the detailed load results for the matching {loadId}. {loadId} is required.
Request Query Parameters
| Parameter | Type | Required | Default | Description |
| resultType | String | no | All Types | Used to filter result messages. Supply: Success, Warning, or Error. |
uploadFile – POST /loader/requests
Load or test loading a supported flat file to ARCOS.
Request Payload
Multipart body that may contain the following form attributes:
Request Form Parameters
| Parameter | Type | Required | Default | Description |
| validateOnly | String | No | 0 | If set to 1, a collection of possible Warnings will be returned, but no file load will be performed. If 0, ARCOS will attempt to load the file and modify system data. |
| file | UTF-8 encoded flat file target | Yes | None | The path of the file to be loaded. Flat File specifications are provided in the Appendix of this manual. |
| type | String | Yes | None | Valid values for the ‘type’ required parameter are: HRI, HRI1, IEX, OTI, OTI2, SDI, SEA, SHIPS, STARS, ULT, CMW1, CMR1, and CML1. Not all types will be available for all companies. If an unsupported type is provided, the load request will be denied. |
| runDate | Datetime | No | Now | |
| arg5 | None | No | None | Not Used. |
Response Payload
A loadRequest element representing the status of the operation. The ‘loadId’ field of each loadRequest will be set to the Load ID field of the newly created operation if successful or to zero if a failure occurred.
Example loadRequest
<loadRequest loadId="1633" filename="SERVICES-HRI-SERVICES-20210604.DAT" type="HRI1"
runDate="Fri Jun 04 11:21:28 EDT 2021" dataRows="1"
loadStatus="Data rows loaded and load initiated. Use loadId to check status">
<warnings/>
</loadRequest>
Example loadResponse
<loadRequest loadId="1633" filename="SERVICES-HRI-SERVICES-20210604.DAT"
type="HRI1" runDate="Mon Jun 28 13:14:14 EDT 2021" dataRows="6"
loadStatus="Data rows loaded and load initiated. Use loadId to check status">
<warnings/>
</loadRequest>
To load a file using the API
- Following the guidance of the preceding sections of this manual, ensure you have a tool established to perform the API operation such as cURL.
- Ensure you have a proper Authentication method prepared as described in the Authentication section of this manual.
- Create the flat file that you desire to load by referring to the appropriate Flat File Specifications provided in the Appendix of this manual.
- Execute a POST operation on the /loader/requests endpoint with appropriate parameters as defined in the uploadFile method section above.
- The loadId provided in a successful response can be used with getLoadSummary and getLoadDetail as a way to retrieve the load results.
Example: Load HRI1 file to ARCOS QA using cURL
curl -i -X POST -H "Authorization: Basic [base64EncodedUserPass]"
-F "file=@CUSTOMER-HRI1-CUSTOMER-YYYYMMDDHHMM.DAT"
-F "type=HRI1" https://qa.rostermonster.com/arcos/rest/loader/requests
Example: The API will respond with the LoadRequest
<loadRequest loadId="1" filename="HRI_file.DAT" type="HRI" runDate="Wed Nov 09 13:29:46 EST 2016" dataRows="26" loadStatus="Pending"/>
Web UI Functionality
To optimize data importing, the loader tool can be used through the API as well as the web UI. ARCOS data importation is done through a flat file system.
To build a file
The Loader functionality allows customers the ability to load their own flat files (HRI, OTI, SDI, etc) into the ARCOS application. The most common file type available for loading these files is CSV. We will use a .csv file to show the processes of building a Human Resources Interface (HRI) file type. Please reference HRI (Human Resources / Employee Data) in this document appendix for formatting details.
Row / Column
For the HRI the required fields are –
HEADER -
Record Type = 100
Company Identifier = COMPANY NAME
Export Date and Time = Time set for the export to take place
Export Record Count = 1
BASIC EMPLOYEE DATA
Record Type =200
Emp_Id = 12345
WEB Login ID = 98745
VRU-ID = 11223344
First Name = George
Last name = Michael
Job Classification Code = 1001
Location Code = 9990
To load a file
Click on the Load Data button to begin the data loading process.
The ensuing page is composed of several ‘panes’. The pane at the top left of your screen contains the tools needed to load the data file.
Select File to Import > Choose File option allows searching your computer for a file to load
Type: Represents the type of data being loaded, or the Data Loader to use, i.e., HRI, OTI, SDI, etc. This selector is not used to specify the file type (extension) like .DAT, .txt or .xlsx.
The Type dropdown will contain the following Load Types:
- HRI
- HRI1
- IEX
- OTI
- OTI2
- SDI
- SEA
- SHIPS
- STARS
- ULT
- CMW1
- CMR1
- CML1
Import: provides the opportunity to preview your file; problems with fields/contents are indicated in the preview so that the errors can be corrected before the file is loaded. Hover-over help provides detail of the problem.
NOTE: Some corrections you could make on screen, through the Preview. For example, changing ONE date in ONE field makes sense to do in the Preview. Other corrections you would not make on screen. Major corrections you would make to the file and then re-Import the corrected file, for loading.
Load: loads the file AS MANIPULATED in the Data Preview.
In the event that the file you are attempting to Import/Load is not formatted as expected for the load Type you have indicated (in the Type dropdown), ARCOS will clearly identify the problems so that you can correct them. In the example below, you can see two types of validation warnings: the yellow triangle indicates a potential problem, whereas the red circle indicates an issue that would cause the load to fail.
Another pane on this page – the top right of your screen - provides file details
Data Preview includes Search, Replace and Mask options.
Search will find a string in any field/row in the data preview.
Replace allows “Find/Replace” (like MS Word) with dropdowns to identify the record type to search, the field/column to search.
Mask allows masking or hiding certain fields as part of the load process, so that existing data (in the ARCOS database) is overwritten with dummy data. Example: phone numbers present in the load file may be masked by 111-111-1111 when loaded to ARCOS. Similarly, masking e-mail addresses in the load file prevents an e-mail address from being loaded/saved into ARCOS.
NOTE: Once the Masking tool is used, the masked data cannot be restored by disabling the [Mask] flag. That is, for example, once phone numbers are masked by 1111111111, unchecking the Mask > Phone Numbers box does not restore the phone numbers that were previously masked. To restore these fields, the file will need to be imported again.
These tools will assist with making some corrections to the data in the file without leaving ARCOS.
Finally, a Validation pane at the right of the Data Preview, provides a concise list of any validation errors encountered in the imported file.
Validation pane lists errors or warnings found in the imported file, along with counts (how many times the error occurred)
Additional Notes on using the Load Data functionality
- Ensure that your data file/type
- Does not strip leading zeros
- Does not convert dates entered without / to their exponential representations
- Retaining the file name required by the automated Data Loader will allow the ARCOS System to recognize the appropriate load Type so that the ARCOS user doesn’t need to select a Type.
- If the filename is NOT in the format required by the ARCOS Data Loader, it will be the responsibility of the ARCOS user to select the correct Type for the file during the manual load.
- File types supported (for loading from) are CSV or TXT, AND the same .DAT and/or encrypted file type that the automated Data Loader would be expecting. That is, if the file you’re manually loading was created for the automated Data Loader, and is encrypted as ARCOS would expect, the manual Load option will recognize the encryption and decrypt appropriately.
- There is no ‘schedule’ component to this new functionality. It is not possible to schedule a load to take place, using this functionality, at a future date/time.
- Security: System Admin – New Security feature for Load Data will be made available, along with existing View Load Results feature
XWalks Data
The XWalks endpoint can be used to obtain cross walk IDs for Employees, Locations, and Job Classifications.
Supported Operations
getValues - GET /xwalks
This method returns a collection of Internal IDs and Customer IDs for Locations, Employees, and Classifications.
With the typical accepts header (*/*), the data returned by this method is JSON formatted, an unusual default compared to the majority of our APIs. This method may be forced to return XML formatted structures by passed an accept header of “application/xml” as described in the Background section of this manual.
Request Query Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| type | String | Yes | None | LOC, EMP, CLASS | LOC – Locations EMP – Employees CLASS – Classifications You may provide this prarmeter multiple times to return multiple types. |
| val | String | No | None | Any Customer ID | Returns only results with a matching Customer ID. |
| searchType |
Subscriptions Data
The Subscriptions endpoint may be used to open a DataStream that will push data in real time whenever employee schedule changes are made. Note, Subscription services may require additional configuration by ARCOS.
Supported Operations
subscribeForPush - GET /subscriptions
This method is published in our Web Application Description language (WADL) but not yet described here. Subscription services may require additional configuration by ARCOS. If you require additional information on this method, please speak with an ARCOS Representative.
Request Query Parameters
| Parameter | Type | Required | Default | Description |
| topic | String | no | Now - 365 Days | |
| mediaType | Datetime | no | Now |
cancelSubscription - DELETE /subscriptions
This method is published in our Web Application Description language (WADL) but not yet described here. Subscription services may require additional configuration by ARCOS. If you require additional information on this method, please speak with an ARCOS Representative.
Employee Data
The Employee endpoint can be used to obtain and modify data that is normally access through the Employee tab in the ARCOS Web Application. Employee standard properties will be returned using a collection of Attribute elements. Each Attribute will contain a ‘key’ field that can be used to uniquely identify the Employee property that is represented by the Attribute. A listing of the Attribute keys and the properties they represent is below. Some of the keys may not be available, depending on customer configuration. When creating and updating Employees using the API, the Attribute ‘key’ must be supplied.
Employee data structures can be found in the Appendix – XSD section.
Attribute Keys
| Key | Description of the Attribute |
| vruId | The Voice Response Unit (VRU) ID |
| webId | The Web ID |
| empId | The Employee ID |
| location_id | Level 4 Location |
| class_id | Primary Class |
| status_id | Employee Status (1 = Active, 2 = Inactive, 5 = Deleted) |
| seniority | Seniority Date |
| service | Service Date |
| birth | Birthdate |
| altDate | Alternative Date |
| curr_assign | CurrAssign Date |
| new_emp | Is this a new Employee? |
| supervisor_id | The contactId of the Employee Supervisor |
| is_supervisor | Is this Employee a Supervisor? |
| sec_group_id | Security Group |
| la_group_id | Location Access Group |
| first_name | First name |
| middle_name | Middle name |
| last_name | Last name |
| nickname | Nickname |
| gender | M or F |
| comment | Availability Comment for the Employee |
| en_only | Employee Type |
| oms_id | Outage Management System ID |
| oms_user | Is this Employee an OMS User? |
| vehicle_type_id | The ID of the Vehicle Type for this Employee |
| no_cdl | No CDL |
| record_flag | Can this Employee Record Outbound Messages? |
| skips | Skips |
| adj_hours | Adjusted Hours for the Employee |
| vehicle_id | The ID of the Vehicle for this Employee |
| callback_emp_rel | Should this Employee be called after being released? |
| vehicle_str | The name of the Employee’s Vehicle |
| radio | Radio for the Employee |
| exah_flag | EXAH |
| pay_type | Salaried or Hourly |
| shirt_size | S, M, L, XL, 2XL, 3XL, 4XL, 5XL |
| crew_leader | Is this Employee a Crew Leader? |
| rep_to_id | The ID of the Report to Location |
| sched_alert | Should this employee get a schedule alert? |
| work_loc | The name of the Work Location |
| hrs_worked_alert | Should this employee get an hours worked alert? |
TransferPhone, CoPhone, and Pager devices should maintain a proper call order sequence with no overlap between devices. Only 3 email addresses are supported at this time. The number of WebDevices will vary with customer.
Supported Operations
searchEmployees - GET /employees
Returns a collection of Employee elements that match the provided query. This method supports pagination using the ‘page’ parameter, ‘X-Arcos-Page’ header, and ‘X-Arcos-Total-Pages’ header.
If the response payload could contain over 5000 employee records, the use of pagination is required or the request may fail with an error that the response contains over 5000 records and pagination is required.
| Parameter | Type | Required | Default | Valid Values | Description |
| searchType | String | Yes | None |
contactid, phone, lastname, firstname, webid, vruid, email, locationaccessid, securitygroupid, deviceserviceid, classid, empid, extendedattribute, radio, locationid |
The type of search to perform using the searchString parameter. The searchType is case sensitive, so contactid does not equal contactID. |
| searchString | String | Yes | None | The value for the searchType to use when finding Employees. | |
| changedSince | Datetime | No | None | Reference Definitions |
Only return records that have been modified since this date.
|
| userChangesOnly | Bool | No | 0 | 0, 1 | Exclude from results any changes made by the Data Loader / API. |
| statusType | Int | No | None | ||
| locationId | Int | No | None | ||
| LocationName | String | No | None | ||
| page | Int | No, unless response may contain over 5000 employee elements | None | Number of page | Activates and controls pagination for responses. |
| rosters | Int | No | None | 1 | Enable roster location / classification / List Status associated to the employee be displayed. |
getEmployee - GET /employees/{contactId}
Returns the Employee element that matches the contactId. The “contactId” is the unique ARCOS identifier for the employee element.
Request Query Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| contactId | int | No | None | contactId | Only show records that are for the contactId provided. |
createEmployee - POST /employees
Create a new Employee.
The Employee element to create. The ‘contactId’ should be set to zero (“0”) when creating employees. Each Attribute object must contain the appropriate ‘key’ field for the save operation to be successful. Payload may also be supplied as Multipart and allows the following additional form parameters.
Request Form Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| saveOptions | No | ||||
| noRosterRules | No | ||||
| noOverwrite | No |
Example
<employee contactId="0" statusColor="#000000">
<attributes>
<attribute name="vruId" value="7600002" key="vruId"/>
<attribute name="webId" value="7600002" key="webId"/>
<attribute name="status" value="Delete" id="5" key="status_id"/>
<attribute name="firstName" value="Kyle" key="first_name"/>
<attribute name="lastName" value="Rosa" key="last_name"/>
<attribute name="location" value="McLeod OpCenter" id="9999" key="location_id"/>
<attribute name="classification" value="Arcos User" id="500" key="class_id"/>
<attribute name="securityGroup" value="Level 0" id="999" key="sec_group_id"/>
<attribute name="locationAccessGroup" value="All Access" id="0" key="la_group_id"/>
<attribute name="isSupervisor" value="0" key="is_supervisor"/>
<attribute name="seniorityDate" value="10/13/2020" key="seniority"/>
<attribute name="employeeType" value="Regular" id="0" key="en_only"/>
</attributes>
<address/>
<emails>
<email index="1" address="krosa@arcos-inc.com"
description="krosa_ai" enabled="true" condensed="false" emailProtected="false"/>
</emails>
<phones>
<phone sequence="1" duty="false" trusted="false" pinReq="false" smsEnabled="false"
number="(111) 111-1112"
phoneType="Regular Phone" firstPause="" firstTouchTone="" secondPause="" secondTouchTone="" comments=""/>
</phones>
<pagers/>
</employee>
Response Payload
An OpStatus element representing the status of the operation. The ‘id’ field of each OpStatus will be set to the contactId field of the newly created record if successful or to zero if a failure occurred.
Example
<opStatus id="1884" code="1" message="Contact Data saved successfully: Rosa, Kyle"/>
createEmployees - POST /employees/batch
Create multiple Employees.
Request Payload
The collection of Employee elements to create. The ‘contactId’ should be set to zero (“0”) when creating employees. Each Attribute object must contain the appropriate ‘key’ field for the save operation to be successful. Payload may also be supplied as Multipart and allows the following additional form parameters.
Request Form Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| saveOptions | No | ||||
| noRosterRules | No | ||||
| noOverwrite | No |
Example
<employees>
<employee contactId="0" statusColor="#000000">
<attributes>
<attribute name="vruId" value="7600002" key="vruId"/>
<attribute name="webId" value="7600002" key="webId"/>
<attribute name="status" value="Delete" id="5" key="status_id"/>
<attribute name="firstName" value="Kyle" key="first_name"/>
<attribute name="lastName" value="Rosa" key="last_name"/>
<attribute name="location" value="McLeod OpCenter" id="9999" key="location_id"/>
<attribute name="classification" value="Arcos User" id="500" key="class_id"/>
<attribute name="securityGroup" value="Level 0" id="999" key="sec_group_id"/>
<attribute name="locationAccessGroup" value="All Access" id="0" key="la_group_id"/>
<attribute name="isSupervisor" value="0" key="is_supervisor"/>
<attribute name="seniorityDate" value="10/13/2020" key="seniority"/>
<attribute name="employeeType" value="Regular" id="0" key="en_only"/>
</attributes>
<address/>
<emails/>
<phones/>
<pagers/>
</employee>
</employees>
Response Payload
Common OpStatus.
Example
<opStatuses>
<opStatus id="4290" code="1"
message="VRU Pin has been reset. for: Polo, Marco Contact Data saved successfully: Polo, Marco"/>
</opStatuses>
updateEmployee - PUT /employees
Update an existing Employee.
The Employee element to update. Each Attribute object must contain the appropriate ‘key’ field for the save operation to be successful. Payload may also be supplied as Multipart and allows the following additional form parameters.
Request Form Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| saveOptions | No | ||||
| noRosterRules | No | ||||
| noOverwrite | No |
Example
<employee contactId="1884" statusColor="#000000">
<attributes>
<attribute name="vruId" value="5717781606" key="vruId"/>
<attribute name="webId" value="krosa_ai" key="webId"/>
<attribute name="status" value="Active" id="1" key="status_id"/>
<attribute name="firstName" value="Kyle" key="first_name"/>
<attribute name="lastName" value="Rosa" key="last_name"/>
<attribute name="fullName" value="Kyle,Rosa" key="full_name"/>
<attribute name="location" value="McLeod OpCenter" id="9999" key="location_id"/>
<attribute name="classification" value="Technician" id="1145" key="class_id"/>
<attribute name="securityGroup" value="Admin" id="500" key="sec_group_id"/>
<attribute name="locationAccessGroup" value="All Access" id="0" key="la_group_id"/>
<attribute name="isSupervisor" value="1" key="is_supervisor"/>
<attribute name="supervisor" value="Sullivan, Jake P." id="1950" key="supervisor_id"/>
<attribute name="seniorityDate" value="06/30/2020" key="seniority"/>
<attribute name="employeeType" value="Regular" id="0" key="en_only"/>
</attributes>
</employee>
Response Payload
An OpStatus element representing the status of the operation. The ‘id’ field of each OpStatus will be set to the contactId field of the newly created record if successful or to zero if a failure occurred.
Example
<opStatus id="1884" code="1" message="Contact Data saved successfully: Rosa, Kyle"/>
getExtendedAttributes – GET /employees/extendedAttributes
This method returns a collection of all available extendedAttribute details including their internal IDs, data type, description, name, and more.
Request Query Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| noPseudo | Bool | No | 0 | 0, 1 | If 1, no Pseudo Attributes will be provided in the response element. |
Response Payload
A collection of extendedAttributes, with or without Psuedo attributes included depending on query.
Example
<extendedAttributes>
<extendedAttribute attributeId="1060" name="A TEST ROLE" description="A TEST ROLE" order="999"
dataType="VALUES" attributeStatusId="0">
<category name="Std" id="1000"/>
</extendedAttribute>
<extendedAttribute attributeId="1061" name="B-TEST-ROLE"
description="B-TEST-ROLE" order="999" dataType="VALUES" attributeStatusId="0">
<category name="Std" id="1000"/>
</extendedAttribute>
<extendedAttribute attributeId="1062" name="C-TEST-ROLE"
description="C-TEST-ROLE" order="999" dataType="TEXT" attributeStatusId="0">
<category name="Std" id="1000"/>
</extendedAttribute>
</extendedAttributes>
getExtendedAttributeValues - GET /employees/attributeValues
Retrieve data of available attributes that could be associated to an employee’s account. Employee Attributes are defined by ARCOS. Values can be updated in most cases on the /employees methods. Additional attributes can be created as needed by utilizing Extended Attribute functionality, when available.
The Attribute ID’s provided by this endpoint can also be used to perform extracts via the /employees GET method with the searchType set to extendedAttribute and the search string containing values such as this example:
Which will return all Inactive employees in the target system with pagination enabled.
Request Query Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| attrId | int | Yes | None | Saved Set ID’s provided below | Returns saved set with the matching set ID |
A table of System Attributes and their IDs is available below. These System Attribute ID’s may be provided to this requests attrId parameter value.
System Attributes
| Attribute ID | Description |
| 502 | Vru ID (text) |
| 501 | Web ID (text) |
| 503 | First Name (text) |
| 504 | Middle Name (text) |
| 505 | Last Name (text) |
| 506 | Nickname (text) |
| 512 | Address (text) |
| 513 | Street (text) |
| 514 | Street Two (text) |
| 515 | City (text) |
| 516 | State (AL,AK,NJ, OH,UT,VA etc.) |
| 519 | Area Code (text) |
| 510 | Location (values) |
| 507 | Class (values) |
| 537 | County Code (values) |
| 522 | Email (text) |
| 527 | Employee Type (values: Regular, Crew Mgr, Notify Only, Limited Use) |
| 520 | Exchange (text) |
| 508 | Gender (text) |
| 521 | Last Four (text) |
| 511 | Location Access (values) |
| 518 | Phone Number (text) |
| 509 | Security Group (values) |
| 524 | Seniority Date (date) |
| 536 | Status (values: Active, Inactive, Delete) |
| 532 | Vehicle String (text) |
| 517 | Zipcode (text) |
getEmployeeStub – GET /employees/stubs/{contactId}
Employee Stubs represent a summary of employee data and contact details. This method returns an employeeStub element for the employee with the provided {contactId}.
Response Payload
A single employeeStub element for the record matching {contactId}.
Example
<employeeStub contactId="1884" firstName="Kyle" lastName="Rosa" firstLastName="Kyle Rosa"
fullName="Rosa, Kyle" vruId="5717781606" webId="krosa_ai" className="Technician"
locationName="McLeod OpCenter">
<emails>
<email>krosa@arcos-inc.com</email>
<email>krosa@rostermonster.com</email>
</emails>
<phones>
<phone>+11111111111</phone>
</phones>
</employeeStub>
getEmployeeStubs – GET /employees/stubs
Employee Stubs represent a summary of employee data and contact details. This method returns an employeeStub element for the employees matching the request query.
Request Query Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| searchType | String | Yes | None |
contactid, phone, lastname, firstname, webid, vruid, email, locationaccessid, securitygroupid, deviceserviceid, classid, empid, extendedattribute, radio, locationid |
The type of search to perform using the searchString parameter. The searchType is case sensitive, so contactid does not equal contactID. |
| searchString | String | Yes | None | The value for the searchType to use when finding Employees. | |
| activeOnly | Bool | No | 0 | 0, 1 | Only return records that are for employees with a status of Active. |
| contactId | Int | No | None | contactId |
Response Payload
A collection of employeeStub elements for the records matching the request query.
Example
<employeeStub contactId="1884" firstName="Kyle" lastName="Rosa" firstLastName="Kyle Rosa"
fullName="Rosa, Kyle" vruId="5717781606" webId="krosa_ai" className="Technician"
locationName="McLeod OpCenter">
<emails>
<email>krosa@arcos-inc.com</email>
<email>krosa@rostermonster.com</email>
</emails>
<phones>
<phone>+11111111111</phone>
</phones>
</employeeStub>
getEmployeeWorkingStatus - GET /employees/workingStatus/{contactId}
Returns a Boolean value of true or false. If the employee identified by {contactId} is presently on a “Working” type event in the ARCOS Schedule, the returned payload is “true”. If the employee is not presently on a “Working” type event, the returned payload is “false”.
runRosterRules - POST /employees/runRosterRules
This method exposes an ARCOS procedures to run Roster Rules in the Callout application.
Request Form Parameters
| Parameter | Type | Required | Default | Description |
| runTest | Bool | No | False | If True, only test the execution of roster rules. If False, the roster rules will be updated. |
Response Payload
Common OpStatus.
Example
<opStatus id="ba028767-5212-41c7-a288-683ba49e22fc" code="1"
message="runRosterRules process started successfully with UUID = ba028767-5212-41c7-a288-683ba49e22fc."/>
getSafetyNoticeDetails - GET /employees/getResponse
Retrieve safety notice details for employees within the range of startDate and endDate.
Request Query Parameters
| Parameter | Type | Required | Default | Valid Values | Description |
| startDate | Datetime | Yes | None | Valid Datetime that is prior to the provided endDate. | |
| endDate | Datetime | Yes | None | Valid Datetime that is after the provided startDate. |
saveEmployeeSafety - POST /employees/saveEmployeeSafety
This method is published in our Web Application Description language (WADL) but not yet described here. If you require additional information on this method, please speak with an ARCOS Representative.
Schedule Data
An Employee’s schedule within Arcos ultimately consists of a collection of ScheduleRecords. These ScheduleRecords are created whenever an Employee is given a ScheduledShift, ScheduleException, or ShiftAssignment.
ShiftAssignments essentially represent collections of ScheduledShift objects for an Employee for a given week. Once the ShiftAssignment is created for an Employee, the corresponding ScheduledShift records are automatically created by Arcos. For example, if a Shift is defined as Monday - Friday from 8:00 - 5:00pm, then creating a ShiftAssignment for an Employee for that Shift would create 5 SheduledShift records, one for each day represented in the Shift. Deleting a ShiftAssignment will remove its corresponding ScheduledShift records.
Schedule data structures can be found in the Appendix – XSD section.
Web UI Functionality
Shift Module
Shifts in ARCOS define an employee’s normal work schedule for a week. Shifts are created in the Shift Module and are assigned to employees using the Week Views on the Schedule Module. Once a shift is created, it is available to all locations within the company. Shifts can also have a Refer As value. The Refer As value allows the same shift to have multiple names. For example, a shift may be called M-F 07:00-16:00 in one department but be called Standard Shift in another department.
Once a shift is created, ARCOS creates a system-generated string that it stores in the Signature column on the Shift Schedule and subsequent shift pages called the Shift Signature. The Shift Signature describes the days of the week and the time ranges for the shift.
***Shifts must be created prior to creating an employee’s schedule.
There is a mouse-over on the column titled “Auto-generated shift signature.” The following abbreviations are used for the days of the week:
- Sunday = Su
- Monday = M
- Tuesday = T
- Wednesday = W
- Thursday = R
- Friday = F
- Saturday = Sa
Example 1: If a shift is set for Monday through Friday with a start time of 12:00 and an end time of 20:30, the Signature will look like this: MTWRF12-2030.
Example 2: If a shift has multiple times for the days it is scheduled, such as Monday – Wednesday 12:00 – 20:30 and Thursday-Friday 10:00 – 18:15, the Signature will look like this: MTW12-2030RF10-1815.
The following table provides a description of the functions associated with each button on the Shift tab.
| Button | Function |
| Add Shift | Allows new shifts to be created in ARCOS. |
| Shift Schedule | Allows all shifts to be viewed. It is also the starting point for deletion and modification of shifts. |
| Shift Usage | Indicates how many employees have the shift assigned. |
| Shift Refer As | Allows Refer As values to be added and removed from shifts. |
| Undelete Shift | Allows deleted shifts to be restored to active status. |
Adding Shifts
There is no limit to the number of shifts that can be added to ARCOS. Once a shift is added, it is available to all employees at all locations within a company. Once you create a shift, ARCOS creates a system-generated string that it stores in the Signature column on the Shift Schedule and subsequent shift pages. The information in this column is the days of the week and the time ranges for the shift as you enter it when you create a shift on the Shift Detail page. ARCOS uses this "Signature" that is created for each new, unique shift created on the Shift Detail page to prevent creation of duplicate shifts, so that you must use the Refer As functionality instead.
- Click the Shift tab. The Shift screen displays.
- Click Add Shift. The Shift Detail screen displays.
- Click OK to the Please enter a shift name prompt.
- Enter the name of the new shift in the Shift Name field.
- Select the day the work week begins from the Day of Week dropdown menu in the first row.
- Continue picking days of the week until you have your work week defined.
- Select start and end times from the Times dropdown menus in each row and skip to Step 9, -OR-
Select the start and end times of the two Synchronize Times dropdown menus at the bottom of the Shift Days table, if all or most of the times for each day's schedule are the same.
- Click the Click button in the Synchronize column for each day to which you wish to copy the time that you set in the Synchronize Times field.
- Click the checkbox in the (P) column or the (N) column, if the shift spans two days to tell ARCOS how you wish to "treat" the shift; it either starts on the previous day or ends on the next day.
- Select P if the shift starts on the Previous day. (Selecting Previous indicates the shift STARTED yesterday and ENDS today.)
- Select N if the shift ends on the Next day. (Selecting Next indicates the shift STARTS today and ENDS tomorrow.)
- Repeat Step 9 for each day of the week that the schedule spans days.
- Click Save Shift.
Note: Once the shift is assigned to employees, the shift cannot be modified.
Modifying Shifts
Shifts are modified on the Shift Detail screen. The Shift Detail screen is accessed through the Shift Schedule screen. The Shift Schedule screen is separated into two tables, one containing names of shifts that have Refer As names and the other containing names of shifts that do not have Refer As names. Modifications can be made to the Shift Name, Day of Week, Times, and the day on which the shift starts and ends.
Note: If the shift is assigned to employees, the days and times for the shift cannot be changed.
- Click the Shift Schedule button on the Shift tab. The Shift Schedule screen displays.
- Click the shift’s name. The Shift Detail page will display.
Note: If the shift is assigned to employees, the day and time fields are grayed out.
- Modify the necessary fields. (Modifications may be made to the Shift Name, Day of Week, Times, and the day on which the shift starts and ends.)
- Click the Save Shift button.
Deleting a Shift
Shifts are deleted on the Shift Detail screen. Shifts can be deleted even if employees are currently assigned to them. When a shift is deleted with employees still assigned and working the shift, they will continue to have the shift assigned for those weeks and days and hours that are defined by the shift. However, the deleted shift will not be available to assign to employees via Week Views within the Schedule module.
Note: Once a shift has been deleted, it remains in the system and can be undeleted if needed at a future time.
- Click the Shift Schedule button on the Shift tab. The Shift Schedule screen displays.
- Click the shift’s name. The Shift Detail page displays.
- Check the Delete Shift checkbox.
- Click the Save Shift button.
- Click OK on the pop-up confirm deletion of the shift.
Undeleting a Shift
A shift that has been deleted can be restored to active status by undeleting it.
- Click the Undelete Shift button on the Shift tab. The Shift Schedule (Deleted Shifts) screen displays.
- Click the shift’s name. The Shift Detail page displays.
- Uncheck the Delete Shift checkbox.
- Click the Save Shift button.
Viewing Shift Usage
The Shift Usage screen indicates how many employees have or have had the shift assigned to them at some point in time. It also displays the earliest and latest dates the shift has been assigned to employees through the entire company. The number of employees is a link to the Shift Usage Detail screen, which displays each employee who has been assigned that shift. The details include the employee's location, status, number of weeks assigned to the shift, and the date range of the shift assignment.
- Click the Shift Usage button on the Shift tab. The Shift Usage screen displays.
- Click the number in the Employees Assigned column next to the shift. The Shift Usage Detail page displays.
Schedule Module
ARCOS uses information found in the Schedule module to determine if an employee is available for a callout. The Schedule module displays employee shifts, working statuses, and schedule exceptions in a comprehensive graphical interface and provides easy administration of schedules and statuses on one screen. You can apply shifts for up to a year to one employee or several employees at a time. You can also apply rotating shifts.
There are six different views: 1 Day, 2 Day, 7 Day, 14 Day, 8 Week, and 16 Week. Each view provides the ability to apply selectors that limit the list based on Location, Roster List, Primary Class, Supervisor, or individually selected employees currently displayed.
The following table provides a description of the functions associated with each button on the Schedule tab.
Employees in Deleted or Inactive status will not display in this list.
| Button | Function |
| Displays a 16-week view of shift assignments and allows modifications of the assignments. This view displays only the shift (or Refer As) name. Use this view or the 8 Week view to assign shifts to employees. | |
| Displays an 8-week view of shift assignments and allows modifications of the assignments. This view displays only the shift (or Refer As) name. Use this view or the 16 Week view to assign shifts to employees. | |
| Displays a 14-day view of employee work statuses, including shifts, callouts, holdovers, and exceptions. This view displays the shift (or Refer As) name and the actual hours the employee is scheduled to work each day. It also includes any exceptions. | |
| Displays a 7-day view of employee work statuses, including shifts, callouts, holdovers, and exceptions. This view displays the shift (or Refer As) name and the actual hours the employee is scheduled to work each day. It also includes any exceptions. | |
| Displays the current day's view plus the next day view of employee work statuses, including shifts, callouts, holdovers, and exceptions. This view displays the shift (or Refer As) name and the actual hours the employee hours the employee is scheduled to work. It also includes any exceptions. | |
| Provides a list of current schedule exceptions, by employee, that can be modified to add or remove exceptions as required. | |
| Provides a list of current schedule exceptions, by employee, that can be modified to add or remove exceptions as required. |
Sorting Records in the Scheduler
You can sort all columns in the Week and Day views in the Schedule module in ARCOS. The same steps are required in any of the Schedule screens.
- Place your cursor over the column by which you wish to sort.
- Right-click the mouse and the Sort Type selector displays.
- Select Ascending, Descending, or Cancel. The sort is executed and the screen refreshes.
Employee Schedule Selectors
Sometimes you need to limit the list of employees in a Schedule view so that you can apply shifts or perform other schedule-related tasks with a smaller group. To display a limited set of employees in the Scheduler, you can use one of the Selector options. These Selectors are the same in the Week Views and the Day Views. There are six Selector options in the Schedule module: Location, Roster List, Primary Class, Supervisor, Checked Only, and None. Selectors make it easier to assign shifts to multiple employees by hiding the employees who will not be assigned shifts at that time. This is especially useful when there are many employees in the same location.
| Button | Function |
|
|
Allows you to select multiple locations for which to display schedules. Once you select locations, you can navigate away from the Schedules tab and when you return to the Schedule page, ARCOS will remember your selections. Also, before you logout, ARCOS prompts you to save any selections you made during the session. |
| Allows you to display only selected the Roster List or Lists you wish to view. For example, a Roster List could include all employees on a callout list for emergencies, all employees who work maintenance, all employees who read meters, etc. | |
|
|
Allows you to display only Primary Class (Classification) lists you wish to view. For example, a Primary Class list could include all employees who are Journeymen, all who are Apprentices, all technicians, etc. |
| Allows you to display by Supervisor. A supervisor list only displays those employees who are direct reports of the selected supervisor. Not all companies use this feature. | |
| Allows you to select employees from the list, using the checkbox to the employee names, and then view a list of only those employees and their schedules. | |
|
|
Allows you to reset your list once you have applied a filter or a combination of filters. None is the default display when you use either Week or Day View. |
Displaying by Location
Displaying by location allows you to select multiple locations for which to display schedules. The Location selector is available on all of the views in the Schedule tab. Once you select locations using the Location selector, you can navigate away form the Schedule tab and when you return, ARCOS remembers your selections and displays the Schedule page as such.
To Use the Location Filter
- Click either a Week View or a Day View button.
- Click Location in the Filters field.
- Select the checkboxes to the left of the Location you wish to display.
- Click OK on the Location window. The window closes and the page refreshes with employees from the selected location.
Displaying by Roster List
A roster is a list of employees constructed either as a Workgroup or a Job Class . Both are composed in an order in which employees will be called out for work. The order is based on business rules of the company or associated union.
- Click either a Week View or a Day View button.
- Click Roster List in the Selector field.
- Select the Roster containing the employees to which you wish to assign shifts.
- Click OK. The screen refreshes and only those employees contained in the selected Roster display.
- Click None to turn the Roster List Selector off and return to the full list of employees.
Displaying by Primary Class
Displaying a list sorted by Primary Class is not the same as by Job Class. The Primary Class selector lists all employees in a in the current location regardless of their roster list assignments.
- Click either a Week View or a Day View button.
- Click Primary Class (Pri Class) in the Selector field.
- Select the Primary Class of employees to which you wish to assign shifts.
- Click OK. The screen refreshes and only those employees contained in the selected Primary Class display.
- Click None to turn the Primary Class Selector off and return to the full list of employees.
Displaying by Checked Only
Sometimes viewing a list by Workgroup or Primary Class will not result in displaying the employees necessary. For the situations when you need to "pick and choose" the employees in a location, use the Checked Only Selector.
- Click either a Week View or a Day View button.
- Select the checkboxes in the Select column on the left side of the page for each employee you wish to display.
- Click Checked Only in the Selector field. The screen refreshes and only the selected employees display.
- Click None to turn the Checked Only filter off.
Shift Masking
If a Working Normal Shift schedule record is covered (or partially covered) by a Schedule Exception, the portion of the shift that is covered is considered masked. For example, if an employee is scheduled to work 7:00 am to 4:00 pm but takes a half-day of vacation, half of the shift is "masked" by the vacation exception. This masking is indicated on the Schedule Page daily views by showing the shift records in a light gray font when they are masked by other exceptions. Basically, a masked shift record is ignored by ARCOS, and not displayed.
Other functions that Shift Masking affects:
- Overrides: Consider an employee who has a scheduled shift, but is also on an exception, such as Vacation. A callout is performed, and Vacation is checked as an override. In the past, the employee would NOT be called, because ARCOS still considered them not available due to their shift. With the new shift masking, their Vacation record masks the shift record, so ARCOS considers them Available for the callout.
- Cumulative Hours Worked Calculation: Many companies have an indicator on the Working page that turns an employee's row yellow or red based on how many hours they have worked. In the past, shift hours which were masked by an exception were actually counted into the Cum Hours calculation. Also, many companies have Rest Rules which perform a similar Cumulative Work calculation in order to determine if an employee should be placed on Rest. "Masked" shift records are no longer included in these calculations.
- Schedule Record Detail Popup: If a shift is masked, even partially, there is an indicator in the Schedule Record detail popup that says, "Masked by exception?" YES.
Applying Shifts via ShiftAssign Roster Preference
ShiftAssign allows the user to assign a shift to an entire roster, in turn, scheduling all employees included in the selected roster to that shift.
This option can be found in the Roster List Ordering section of the List Maintenance tab and clicking the admin link for the roster that requires scheduling.
The ShiftAssign, ShiftBaseDate and ShiftNumWeeks roster preferences work together to ensure that employees on the roster always have a shift assigned.
- ShiftAssign: This can be a single shift name or “shift refer as” value, or a comma separated list of shift names or “refer as” values.
Note: This field is case sensitive and must match what’s listed on the Shift tab.
- Comma separated values will allow the ability to assign a rotating shift to a group of people
- Allows up to 200 characters, if shift names are long, shift refer as values should be used
- Can be changed once employees are assigned to the roster. You can add or remove shifts to the rotation, change the order of the rotation, change a non-rotating to a rotating and vise versus
- ShiftBaseDate: The date that the rotation starts. This is only used when creating a shift rotation
- The value in this preference is mm/dd/yyyy and must be in the past.
- The date entered would be the date the first shift within the rotation would be applied to.
- Cannot be changed once employees are assigned to the roster.
- ShiftNumWeeks: The number of weeks into the future the shift configuration is applied to the employees on the roster
- Value must be numeric and at minimum 4 and at most 99
- Can be changed after employees are added to the roster. Shift weeks will be assigned or unassigned depending on which direction the preference is changed.
Shift Example
Shift Assign – Roster List Ordering Example
List Example
Supported Operations
getRecords - GET /schedules/records
Returns a collection of ScheduleRecords that match the specified query.
| Parameter | Type | Required | Default | Description |
| startTime | Datetime | No | Now | Records returned will have started or ended at or after this date. |
| endTime | Datetime | No | Now + 1 Day | Records returned will have started or ended up to and including this time. The endTime - startTime range must be 15 days or less. |
| changedSince | Datetime | No | None | Only return records that have been modified since this date. |
| showInactive | Bool | No | None | Set to 1 to show deleted records in the results. |
| skipScheduledShifts | Bool | No | 0 | set to 1 to filter out ScheduledShift records. |
| skipExceptions | Bool | No | 0 | set to 1 to filter out ScheduleException records. |
| contactId | Array of int | No | None | Only show records that are for the contactIds provided. |
| locationId | Array of int | No | None | Only return records for Employees that are in the locationIds provided. locationIds will only be considered if contactId is not used. |
| eventId | Array of int | No | None | Only return records that have Event Types that match the eventIds provided. |
| userChangesOnly | Bool | No | 0 | |
| skipImported | Bool | No | 0 | |
| modifiedOnly | Bool | No | 0 | |
| custIdType | List | No | None | |
| custIdValue | List | No | None |
getShiftsAssignments - GET /schedules/shifts
Returns a collection of ShiftAssignments that match the specified query.
| Parameter | Type | Required | Default | Description |
| startTime | Datetime | no | now | Records returned will have assignmentStart dates at or after this date. |
| endTime | Datetime | no | now + 7 days | Records returned will have assignmentStart dates up to this date. |
| changedSince | Datetime | no | none | Only return records that have been modified since this date. |
| contactId | Array of int | no | none | Only show records that are for the contactIds provided. You may provide this parameter multiple times for multiple contactIds. |
| locationId | Array of int | no | none | Only return records for Employees that are in the locationIds provided. locationIds will only be considered if contactId is not used. You may pass multiple locationIds by passing this parameter multiple times. |
getShifts - GET /shifts
Returns a collection of ShiftAssignments that match the specified query.
Request Query Parameters
| Parameter | Type | Required | Default | Description |
| getShiftDays | int | |||
| getReferAsList | int |
getEmployeeSchedules - GET /schedules/employeeSchedules
Returns a collection of EmployeeSchedules that match the specified query. The EmployeeSchedule will contain some basic information about the employee as well as their ShiftAssignments and ScheduleRecords for the given startTime and endTime.
| Parameter | Type | Required | Default | Description |
| startTime | Datetime | no | now | Records returned will have started or ended at or after this date. |
| endTime | Datetime | no | now + 1 day | Records returned will have started or ended up to and including this time. The endTime - startTime range must be 15 days or less. |
| changedSince | Datetime | no | none | Only return records that have been modified since this date. |
| skipShiftAssignments | int | no | 0 | set to 1 to filter out ShiftAssignment records. |
| skipScheduledShifts | int | no | 0 | set to 1 to filter out ScheduledShift records. |
| skipExceptions | int | no | 0 | set to 1 to filter out ScheduleException records. |
| showInactive | int | no | none | Set to 1 to show deleted records in the results. |
| contactId | Array of int | no | none | Only show records that are for the contactIds provided. |
| locationId | Array of int | no | none | Only return records for Employees that are in the locationIds provided. locationIds will only be considered if contactId is not used. |
Sync - GET /schedules/sync
Returns information for schedules with assignment dates between startTime and endTime and/or schedules that have changed since the changedSince date. Please note that this method returns dates in Arcos time (EST), in this format: 2021-08-27T18:36:57-04:00. This method returns OutputStream, which contains XML or JSON string - depending on the 'Accept' header value set in the request.
Request Query Parameters
| Parameter | Type | Required | Valid Values | Default | Description |
| startTime | Datetime | Y | ISO-8601 Datetime | null | An item must exist (not be deleted) AFTER this date. If changedSince is present, and startTime is not given, all records will be analyzed. In the absence of changedSince, both startTime and endTime must be given, and should be no more than 365 days apart. |
| endTime | Datetime | Y | ISO-8601 Datetime | null | An item must have been created BEFORE this date.If changedSince is present, and endTime is not given, all records will be analyzed. In the absence of changedSince, both startTime and endTime must be given, and should be no more than 365 days apart. |
| changedSince | Datetime | N | ISO-8601 Datetime | 1970-01-01 |
Query will return only records which have either been added or changed since this date - but only if the record satisfies the startTime and endTime parameters. If the changedSince is provided, but the time range between startTime and endTime exceeds 365 days, OR one of both of those dates are missing, then the changedSince cannot go back more than 90 days. |
| userChangesOnly | Bool | N | 0, 1 | 0 | If set to 1, results will NOT include records changed by Loader processes. |
| action | String | N | See Description | employeeSchedules |
Describes the format of response. The default value is employeeSchedules, which results in the response similar to schedules/employeeSchedules call, which schedule records wrapped into employeeSchedule element. Another valid option is schedulesOnly. That will return schedule elements only, without employee information. |
| skipShiftAssignments | Bool | N | 0, 1 | 0 | If set to 1, Shift Assignments will not be included. |
| skipScheduledShifts | Bool | N | 0, 1 | 0 | If set to 1, Scheduled Shifts records will NOT be included. |
| skipExceptions | Bool | N | 0, 1 | 0 | If set to 1, Schedule Exceptions records will NOT be included. |
Response Payload
A collection of employeeSchedules that match the query parameters.
Example
<employeeSchedules>
<employeeSchedule contactId="288" vruId="6143965108" webId="chapman_ai" empId="Not Found" name="Chapman, Mitch" locationId="9999">
<shiftAssignments></shiftAssignments>
<scheduledShifts>
<scheduledShift memexId="65792" contactId="288" treatAs="2021-10-19T00:00:00-04:00" isHoliday="false" isWorkingHoliday="false" modified="false" eventId="1008" startTime="2021-10-19T07:00:00-04:00" endTime="2021-10-19T14:00:00-04:00" isActive="true" locationId="9999" vehicleId="0" restFlag="0" addDate="2020-09-27T00:48:03-04:00" changeDate="2020-09-27T00:48:03-04:00"></scheduledShift>
</scheduledShifts>
<scheduleExceptions></scheduleExceptions>
</employeeSchedule>
</employeeSchedules>
getScheduleRecord - GET /schedules/{memexId}
Returns the ScheduleRecord that matches the provided {memexId}.
Request Query Parameters
| Parameter | Type | Required | Default | Description |
| tz | String | no | Location Time Zone | Datetime attributes in any element returned will be skewed to the supplied Time Zone. (Such as: “US/Eastern”) |
The scheduledShift with matching {memexId}.
Example
<scheduledShift treatAs="2021-04-21T00:00:00-04:00" isHoliday="false"
isWorkingHoliday="false" modified="false" memexId="46646" contactId="1260" eventId="1008"
startTime="2021-04-21T10:00:00-04:00" endTime="2021-04-21T19:00:00-04:00" isActive="false"
locationId="0" vehicleId="0" restFlag="0" addDate="2020-05-13T11:54:57-04:00"
changeDate="2021-04-21T12:02:45-04:00"/>
createRecords - POST /schedules/records
Create new ScheduledShifts or ScheduleExceptions. The ‘memexId’ attribute should be set to zero when creating new records.
A collection of ScheduleRecord objects consisting of either ScheduledShifts or ScheduleExceptions.
Example
<scheduleRecords>
<scheduledShift contactId="4353" endTime="2021-08-02T17:00:00-04:00" eventId="1008" memexId="0" startTime="2021-08-02T09:00:00-04:00" />
</scheduleRecords>
A collection of OpStatus elements for each ScheduleRecord provided. The ‘id’ field of each OpStatus will be set to the memexId field of the newly created record if successful or to zero if a failure occurred.
Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opStatuses>
<opStatus id="77537" code="1" message="Schedule has been saved for contact 4353"/>
</opStatuses>
createShift - POST /shifts
Create new shiftAssignment patten templates.
Request Payload
A Shift objects consisting of shiftDays and optionally referAs.
Example
<shift name="tl_17">
<shiftDays>
<shiftDay dayOfWeek="Sunday" startTime="1400" endTime="0230" startsOnPreviousDay="true"
endsOnNextDay="false"/>
<shiftDay dayOfWeek="Tuesday" startTime="0100" endTime="0530" startsOnPreviousDay="false"
endsOnNextDay="false"/>
<shiftDay dayOfWeek="Wednesday" startTime="1900" endTime="0530" startsOnPreviousDay="true"
endsOnNextDay="false"/>
<shiftDay dayOfWeek="Thursday" startTime="0100" endTime="0530" startsOnPreviousDay="false"
endsOnNextDay="false"/>
<shiftDay dayOfWeek="Friday" startTime="2300" endTime="0530" startsOnPreviousDay="true"
endsOnNextDay="false"/>
</shiftDays>
<referAsList>
<referAs referAs="TL-17_1" locationId="9999"/>
<referAs referAs="TL-17_2" locationId="9999"/>
<referAs referAs="TL-17_3" locationId="4177"/>
</referAsList>
</shift>
Response Payload
A collection of OpStatus elements for each shift provided. The ‘id’ field of each OpStatus will be set to the shiftId field of the newly created record if successful or to zero if a failure occurred.
updateRecord - PUT /schedules/records/{memexId}
This method can be used to update the ScheduleRecord provided. Only ‘startTime’, ‘endTime’, ‘comment’, ‘vehicleId’, ‘isWorkingHoliday’, and ‘releaseFlag’ may be changed.
The ScheduledShift or ScheduleException that should be modified.
Example
<scheduledShift treatAs="2021-02-15T00:00:00-05:00" isHoliday="false" isWorkingHoliday="false" modified="false" memexId="214247" contactId="1151" eventId="1008" startTime="2021-02-15T00:00:00-06:00" endTime="2021-02-15T08:00:00-06:00" isActive="true" locationId="0" vehicleId="0" restFlag="0" addDate="2021-02-25T09:35:25-05:00" changeDate="2021-02-25T09:35:25-05:00"/>
An OpStatus element representing the result of the operation.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opStatus id="0" code="404" message="Schedule Record was not found for memexId 214247"/>
updateRecords - PUT /schedules/records
This method can be used to update the ScheduleRecords provided. Only ‘startTime’, ‘endTime’, ‘comment’, ‘vehicleId’, ‘isWorkingHoliday’, and ‘releaseFlag’ may be changed.
Request Payload
The ScheduledShifts or ScheduleExceptions that should be modified.
Response Payload
An OpStatus element representing the result of the operation.
deleteRecord - DELETE /schedules/records/{memexId}
Sets the delete flag on the ScheduleRecord specified by memexId. Future searches for ScheduleRecords will only return this record if the showInactive flag is set to one (1). Searches for ScheduleRecords by specific memexId, however, will return records regardless of the showInactive setting.
An OpStatus object representing the result of deleting the ScheduleRecord.
createShifts - POST /schedules/shifts
Create new ShiftAssignments. Employees will have at most 1 ShiftAssignment per week. Attempting to create multiple ShiftAssignments for the same week will result in the last ShiftAssignment being saved and the others being overwritten.
Note, the createShifts method is also used to Delete Shifts. ShiftAssignments are removed by setting the ‘shiftId’ to zero(0) for the desired assignment date.
A collection of ShiftAssignment objects in either XML or JSON data structures.
A collection of OpStatus elements for each ShiftAssignment provided. The ‘id’ field of each OpStatus will be set to the memexId field of the newly created ShiftAssignment if successful or to zero if a failure occurred.
getScheduleRequests - GET /schedules/scheduleRequests
This method returns a collection of Schedule Request records matching the provided search query.
Request Query Parameters
| Parameter | Type | Required | Default | Description |
| supId | Int | No | None | |
| deleted_flag | No | None | ||
| search_date | Datetime | No | None | |
| schedRequestIds | Int | No | None | |
| contactIds | Int | No | None |
getScheduleRequest - GET /schedules/scheduleRequest/{schedRequestId}
This method returns the Schedule Request records matching the provided {schedRequestId}.
CONTINUED
Comments
0 comments
Please sign in to leave a comment.