The eConnect API is a generic API for accessing service calls placed at Onitio. You can search for service calls, create new service calls and update existing service calls. All aspects related to a service call can be handled trough the API. You can handle parts, manipulate cost lines, upload attachments and so on.
The API is based on JSON, i.e. the API accepts JSON as input and will return JSON as output. All API calls are documented with samples here. We have also provided a sample project which is documented here
We assume that you have some familiarity with the Onitio service model, i.e. that you know what we mean by an activity, a requisition line, a cost line, a workflow and so on. If you are unfamiliar with these terms you should brush up your knowledge by reading the Workflows and activities page which describes the most important features of the Onitio service model.
If you run into any problems please contact us at systemsupport@infocare.com
All API methods requires a valid user identification, this identifier is obtained by calling one of the Logon methods on the Account controller. However, not all users will have access to everything so we will kick of this introduction with an overview of user and user types.
Note that the only type of user you can create through the API is an external user. If you need any other kind of user you will have to contact Onitio.
Let us assume that a partner has the following setup
This means that the partner can see activities registered on contracts A,B and C regardless of who the activity was created by. Partner can also see activities registered on contract D provided that activity was created by the partner. Partner can use contracts A,B and D to create new activities.
Let us further assume that we have user from the partner that have the following additional restrictions
This means that this partner user is limited to contract A, hence this user can only see activities registered on contract A. This partner user will also only be allowed to create activities on contract A.
We have defined several security groups or security roles if you like in eConnect. Every user is member of at least one security group. The combination of user type and security roles govern what a user is allowed to do in eConnect.
Several of the API object models uses the same model for fields, for example so are the properties of an activity returned as fields, same apply to cost lines, requisition lines, user information and so on. We will the next chapter describe which fields you can expect available for each object. We are starting off with the activity object.
We have written security groups without the prefix SFSEC_ in order to save some space in the table below. Also note that you do not have to check for security rights yourself, as a developer you only have to check the IsEnabled property of the FieldModel. The create and edit rights columns are included to give you a better understanding of why certain fields always are disabled. Also note that even if the create/edit column indicates that you should have the right to modify a field it may still be disabled according to the rules set on the work flow.
The activity object contains a lot of field, but you do not necessarily have to fill out all fields. Check the IsRequired property of the FieldModel to see if you have to fill out a field or not. Please note that the requiredness of a field is not constant, it may change during a the lifetime of an activity. For example so will probably "Product.SerialNumberOut" be optional in the early stages of the work flow, but the field may become required when you about to leave the customer.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| CombinedActivityId | Unique identifier for the activity. Please note that a newly created activity does get an id until it is saved for the first time. | None | None |
| SecurityCode | Security code for activity, can be used in combination with the CombinedActivityId to create a logon ticket for gaining access to the activity | None | None |
| ProblemDescription | Used for describing the problem or task you should solve. | All | All |
| SolutionDescription | Used to describe how the problem or task was solved | EndUser, SubContractor, TrustedPartner, InfoCare | SubContractor, PartnerAdministrator, InfoCare |
| InvoiceReference | Used to store invoice reference | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| SpecialReference | Some customers have additional reference information that we need to store | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| WarrantyReference | Used to store warranty reference | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| CustomerReference | Used to store customer reference information | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| Contract.ContractId | Used to store the identity of the contract this activity belongs to. This is a read-only field. | None | None |
| Contract.Name | Used to store the name of the contract this activity belongs to. This is a read-only field. | None | None |
| ServiceDescription | Used to store what kind of service level Onitio will provide for this activity, for example "Onsite next business day", "Fixed withing 3 days" and so on. | None | None |
| Originator | If activity is created by a partner user we will use the originator defined for this partner, otherwise originator will be set to Sunflower. This field can be updated by InfoCare users. | None | InfoCare |
| EstimatedStart | Tells us when technician is supposed to start working on the activity. This is a read-only field. | None | None |
| EstimatedEnd | Tells us when technician is supposed to finnished working on the activity. This is a read-only field. | None | None |
| EstimatedTravelDuration | Tells us how long it should take the technician to reach the customer site. This is a read-only field. | None | None |
| SuggestedWorkDuration | Tells us how long it is assumed to take the technician to work on an activity when present at the customer site. This field can only be changed at activity creation. | TrustedPartner, InfoCare | None |
| AssignedGroup | Used to store which group the activity is assigned to. Field can only be set if activity is an assign step, but may be indirectly changed while traversing the workflow. Please note whether the field is required or not will be determined by the workflow step you attempt to make. Note that field will only be present if you either are an Onitio user or if you are a SubContractorAdministrator and the activity has been assigned to your company. | None | Onitio |
| AssignedResource | Used to store which resource the activity has been assigned to. A resource may be an InfoCare technician or a subcontractor company. Field can only be set if activity is an assign step, but may be indirectly changed while traversing the workflow. Please note whether the field is required or not will be determined by the workflow step you attempt to make. Note that field will only be present if you either are an InfoCare user, if you are a partner with role PartnerIntegrator or if you are a sub-contractor and the activity has been assigned to your company. | None | InfoCare |
| SubAssignedResource | If activity is assigned to a subcontractor the subcontractor can further sub-assign the activity to one of the technicians working for the subcontractor. The subcontractor must have been configured use sub-assignment. Note that field will only be present if you either are an InfoCare user, if you are a partner with role PartnerIntegrator or if you are a sub-contractor and the activity has been assigned to your company. | None | SubContractorAdministrator |
| CreatedAt | Date and time for when activity was created | None | None |
| CreatedBy | Name of person that created the activity. Note that if you are a subcontractor or partner user the created by name will only be present if the created by person is registered as a user in your company. If you are an external user or single activity user you will only see the created by person if it was you that created the activity. If you are an InfoCare user you will always be able to see the created by user. | None | None |
| Product.Name | Name of product that is not working, i.e. the product we are going to repair | EndUser, SubContractor, PartnerAdministrator, InfoCare | TrustedSubContractor, SubContractorAdministrator, PartnerAdministrator, InfoCare |
| Product.Brand | Brand of product that is not working | EndUser, SubContractor, Partner, InfoCare | TrustedSubContractor, SubContractorAdministrator, Partner, InfoCare |
| Product.Description | Used for a more textual description of the product, where Product.Name may be something like IPP350v3-4.32-NEW, the Product.Description might be "Payment terminal" | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedSubContractor, SubContractorAdministrator, TrustedPartner, InfoCare |
| Product.SerialNumber | Used to store the old serial number | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedSubContractor, SubContractorAdministrator, TrustedPartner, InfoCare |
| Product.SerialNumberOut | Used to store the new serial number | EndUser, InfoCare | SubContractor, InfoCare |
| Product.SerialNumberCustomer | Used as an additional serial number field. | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| Product.Imei | Used to store the IMEI number when the product is a mobile device | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| Product.ImeiOut | Used to store an additional IMEI number when the product is a mobile device | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| Product.PriceCategory | Used to store price category | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| Product.PurchaseDate | Purchase date for product | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| SiteCustomer.Name | Name of site customer | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| SiteCustomer.AdditionalInfo | Extra information about the site customer | EndUser, SubContractor, TrustedPartner, InfoCare | InfoCare |
| SiteCustomer.Address | Site customer street address | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedSubContractor, SubContractorAdministrator, TrustedPartner, InfoCare |
| SiteCustomer.ZipCode | Site customer zip code | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedSubContractor, SubContractorAdministrator, TrustedPartner, InfoCare |
| SiteCustomer.City | Name of site customer city | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedSubContractor, SubContractorAdministrator, TrustedPartner, InfoCare |
| SiteCustomer.Country | Country is identified by its calling code, e.g. 47 for Norway, 45 for Denmark and so on | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedSubContractor, SubContractorAdministrator, TrustedPartner, InfoCare |
| SiteCustomer.PhoneNumber | Site customer phone number | EndUser, SubContractor, TrustedPartner, InfoCare | SubContractor,TrustedPartner, InfoCare |
| SiteCustomer.WorkPhone | Additional phone number for customer | EndUser, SubContractor, TrustedPartner, InfoCare | SubContractor,TrustedPartner, InfoCare |
| SiteCustomer.MobileNumber | Site customer mobile phone, note that number may be used to send automatic SMS messages so please take care to fill it out with an actual mobile number | EndUser, SubContractor, TrustedPartner, InfoCare | SubContractor,TrustedPartner, InfoCare |
| SiteCustomer.ContactPerson | Name of the contact person at the site customer | EndUser, SubContractor, TrustedPartner, InfoCare | SubContractor,TrustedPartner, InfoCare |
| SiteCustomer.eMail | eMail address for site customer | EndUser, SubContractor, TrustedPartner, InfoCare | TrustedPartner, InfoCare |
| CustomProperty.* | An activity may have zero or more additional fields. These additional fields are called custom properties. The field name always start with the prefix CustomProperty. which is followed by a GUID identifying the custom property. Use the FieldLabel property of the FieldModel to get a human readable name. Please note that the name might not be unique. All custom properties will have same basic access rights. | EndUser, SubContractor,TrustedPartner, InfoCare | SubContractor,TrustedPartner, InfoCare |
| DefaultCommentVisibillity | Flag to set or unset the default visibility of a comment | None | None |
| DefaultAttachmentVisibillity | Flag to set or unset the default visibility of an attachment | None | None |
A comment on an activity is represented by a CommentModel which will always contain three fields on the FieldModel format. When adding a new comment the fields that have to be defined is the Comment field, CreatedAt will always be set to system time the comment is added and CreatedBy will be set to currently logged on user. The IsVisible field is optional and specifies whether the comment will be visible or not. If not specified visibility will be set according to existing rules: That is, for subcontractor and enterprise users IsVisible is set according to the activity workflow VisibilityOnComments field. For ServiceUsers and ExternalUsers IsVisible will be always set to true. If the IsVisible value is specified it will only be considered for InfoCare users. For any other user visibility will be set according to the rules explained previously.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| CreatedAt | The date for when the comment was added | None | None |
| CreatedBy | The person or entity that added the comment | None | None |
| Comment | The free text comment | All | None |
| IsVisible | Visibility of the comment | All | None |
A schedule on an activity is represented by a ScheduleModel. The model consists of a couple of read only fields, like personal deadline, official deadline, name and id of schedule in addition to two lists: Delays and Fails. These two lists are used to change a schedule; Delays are used to extend the deadline while Fail is used to tell why the schedule failed.
If you want to extend a schedule you add a new ScheduleDelay to the schedule Delay list. We recommend that you use the Activity.CreateAttributeTemplate to get a valid schedule delay template. Note that you are not allowed to change existing entries, you are only allowed to add new entries. The Fields list of the DelayModel may contains the following entries.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| CreatedAt | When the delay was made, field will be set automatically | None | None |
| CreatedBy | Who made the delay, field is set automatically | None | None |
| PersonalDeadline | Personal time | SubContractor, PartnerIntegrator, InfoCare | None |
| OfficalDeadline | Official deadline, cannot be set directly. Will be changed automatically if delay reason is considered a "valid" reason | None | None |
| DelayReason | The reason for making the delay, this field may be optional | SubContractor, PartnerIntegrator, InfoCare | None |
| DelayDescription | A supplementary text explaining the delay if needed. | SubContractor, PartnerIntegrator, InfoCare | None |
When you reach the end of the schedule and you have failed to meet the deadline you may have to state why you have failed to meet the deadline. In these cases you will have to add a FailModel to your schedule. We recommend that you use the Activity.CreateAttributeTemplate to get a valid schedule fail template. Note that you are not allowed to change existing entries, you are only allowed to add new entries. The Fields list of the FailModel may contains the following entries.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| CreatedAt | When the delay was made, field will be set automatically | None | None |
| CreatedBy | Who made the delay, field is set automatically | None | None |
| FailReason | The reason for failing the schedule | SubContractor, InfoCare | None |
A cost on an activity is represented by a CostLineModel which will always contain five fields on the FieldModel format. When creating a new cost line none of the fields has to be defined, the only exception being description for costs where the definition requires it. The other fields gets default values from the system. See LookupController.GetAvailableCostSetDefinitions(ActivityIdArgumentModel) to get a list of available definition id's for the specific activity.
Infocare and sub contractor users have full access to cost lines, partner users have limited accessed based on their security roles- Partner users with role PartnerIntegrator will be able to see but not modify cost lines, partner users with role PartnerIntegratorWithCostLine will be able to both see and modify cost lines. However, they will only be allowed to modify existing cost lines that does not have an owner. Partner users will not be allowed to add new cost lines.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| CreatedAt | The date for when the cost occurred | SubContractor, InfoCare, PartnerIntegratorWithCostLine | SubContractor, InfoCare, PartnerIntegratorWithCostLine |
| CreatedBy | The person or entity that created the cost line | None | None |
| Name | Name of the cost line, is determined from it's definition | None | None |
| IsCostlineRequired | Returns true if a costline is required and false otherwise | None | None |
| PriceCategory | Price category of the cost line | None | None |
| Description | Text with more explanation regarding the cost line, for instance Distance based costs needs the route taken described | SubContractor, InfoCare, PartnerIntegratorWithCostLine | SubContractor, InfoCare, PartnerIntegratorWithCostLine |
| Currency | Currency used on cost line | None | None |
| CostLineQuantity | Current customer quantity on the cost line. Not editable. Requires security group CostProposalStatuses to read | None | None |
| CostLineUnitPrice | Current customer unit price on the cost line. Not editable. Requires security group CostProposalStatuses to read | None | None |
| CostLineDiscount | Current customer discount on the cost line in percentage. Not editable. Requires security group CostProposalStatuses to read | None | None |
| CostLineNetTotal | Current customer net total on the cost line. Not editable. Requires security group CostProposalStatuses to read | None | None |
| InvoiceStatus |
Invoice status for the cost line. Valid values. Not all statues can be used when updating the cost line.
|
Infocare | Infocare |
| Quantity |
The total quantity, amount or cost represented by the cost line. The cost type can be represented by one of the following types:
|
SubContractor, InfoCare, PartnerIntegratorWithCostLine | SubContractor, InfoCare, PartnerIntegratorWithCostLine |
When you create a new requisition line you have to specify PartNumber, Quantity and OrderType, you may optionally specify stock and delivery information. Most if these fields will be locked for direct update for existing requisition lines, but some can be indirectly changed by applying requisition functions. Based on rules specified in the OrderType it is possible to create a requisition line with no delivery customer specified. It is, however, not possible to update this requisition line before delivery customer is specified.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| PartNumber | Part number. Must be set when creating a requisition line, but can only be changed indirectly by applying a requisition function for an existing requisition line | SubContractor, PartnerIntegrator, InfoCare | None |
| PartName | Part name, can be changed indirectly by changing part number or can be set during requsition line creation, but only if part number does not exist in our part database. In this case the part is created on the fly using the specified part number and part name | PartnerIntegrator | None |
| Quantity | Number of parts ordered. Must be set when creating a requisition line. | SubContractor, PartnerIntegrator, InfoCare | None |
| Stock | Stock number, tells you were that part is ordered from (if part is available on that stock), and where that part is connected to if part is ordered from an supplier. Can be set when creating a new requisition line, which will override default value. | SubContractor, PartnerIntegrator, InfoCare | None |
| StockName | Name of stock, is indirectly set by setting stock | None | None |
| Priority |
Must be set when creating a requisition line. Default value will be set based on the order, but can be changed. Valid values:
|
SubContractor, PartnerIntegrator, InfoCare | None |
| ShipmentType | Must be set when creating a requisition line. Default value will be set based on the order type. | SubContractor, InfoCare | None |
| Supplier | Supplier for this requisition. Default value will be set based on the order type. | SubContractor, PartnerIntegrator, InfoCare | None |
| OrderType | Must be set when creating a requisition line. The order types determine how the part should be handled. | SubContractor, PartnerIntegrator, InfoCare | None |
| LowestCompletedZone |
Tells us how far the part has progress through its part workflow. The following zones are defined
|
None | None |
| EstimatedDeliveryStatus | Status connected to Estimated delivery date | None | None |
| EstimatedDeliveryDate | Estimated delivery date | None | None |
| DeliveryCustomerName | Name of delivery customer | SubContractor, PartnerIntegrator, InfoCare | SubContractor, PartnerIntegrator, InfoCare |
| DeliveryCustomerAdditionalInfo | Additional address information about delivery customer | SubContractor, PartnerIntegrator, InfoCare | SubContractor, PartnerIntegrator, InfoCare |
| DeliveryCustomerAddress | Street address of delivery customer | SubContractor, PartnerIntegrator, InfoCare | SubContractor, PartnerIntegrator, InfoCare |
| DeliveryCustomerZip | Zip code for delivery customer | SubContractor, PartnerIntegrator, InfoCare | SubContractor, PartnerIntegrator, InfoCare |
| DeliveryCustomerCity | City for delivery customer | SubContractor, PartnerIntegrator, InfoCare | SubContractor, PartnerIntegrator, InfoCare |
| DeliveryCustomerContact | Contact name | SubContractor, PartnerIntegrator, InfoCare | SubContractor, PartnerIntegrator, InfoCare |
| CustomProperty.* | A requisition line may have zero or more additional fields. These additional fields are called custom properties. The field name always start with the prefix CustomProperty. which is followed by a GUID identifying the custom property. Use the FieldLabel property of the FieldModel to get a human readable name. Please note that the name might not be unique. All custom properties will have same basic access rights. | SubContractor,TrustedPartner, PartnerIntegrator, InfoCare | SubContractor,TrustedPartner, PartnerIntegrator, InfoCare |
An attachment is represented by the AttachmentModel. The AttachmentModel does not have a variable number of fields so all fields are directly defined in the model. It is not possible update an attachment, you will have to delete it first and then upload a new attachment. Please note that attachments must uploaded by using UploadFile. Attachment are removed by using RemoveFile
A workflow step is represented by WorkflowStepModel. In addition to the fixed properties ID and Name a WorkflowStepModel has a a list of fields in the Fields property. You may find the following objects in the table below. When adding a new WorkflowStep you should call LookupController.GetAvailableWorkflowSteps(ActivityIdArgumentModel) to get a list of allowable steps.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| CreateAt | When step was started, note that not all steps may allow setting this value when you create a new step. Check IsEnabled from the WorkflowStepDefinition | InfoCare, SubContractor | None |
| CreatedBy | Who created the step | None | None |
| CompletedAt | When the step was completed | None | None |
| CompletedBy | Who completed the step | None | None |
| StartLocation | Where the step was started | InfoCare, SubContractor | None |
| EndLocation | Where the step was completed | None | None |
A user is represented by a UserModel. The UserModel has a number of fields on the FieldModel format specified below. Only external users can create a new user when registering an activity in eConnect. InfoCare, partner and subcontractor users have to be predefined before registering and/or viewing cases.
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| FirstName | First and middle name | EndUser | All |
| LastName | Sir name | EndUser | All |
| OrganisationNumber | The user's organization number if an external user is company. | None | EndUser |
| Company | The user's company id. Only relevant for partner and subcontractor users | None | None |
| Address | The user's address | EndUser | All |
| Zip | The user's zip code | EndUser | All |
| City | The user's city | EndUser | All |
| The user's e-mail. The e-mail is used as user name when logging on to eConnect | EndUser | None | |
| Mobile | The user's mobile phone number | EndUser | All |
| Phone | The user's phone number | EndUser | All |
| Password | The user's personal password to be used when logging on to eConnect | EndUser | All |
The method GetSerialNumberHistory returns an object which contains a collection of objects each of which contains detailed information about the serial number history changes. The model layout is as follows:
| Field name | Description | Create rights | Edit rights |
|---|---|---|---|
| CombinedPerformanceId | Performance Monitoring id (this field is not really relevant but required for internal operation of the API | None | None |
| SerialNumberHistory |
A collection of objects each of which contains detailed information about the serial number history changes represented bythe following types:
|
None | None |