Introduction

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

User and user types

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.

Partner access example

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.

Security groups

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.

Note that it is not possible to change group memberships through the API. If need to change the security role for a specific user you will have to contact Onitio. Users created through the Account.CreateUser are automatically made member of the SFSEC_EndUser group.

Activity fields

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

Comment fields

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

Schedule fields

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.

Delays

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

Fails

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

Cost line fields

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.
  • 4, WaitForCustomerFeedBack
  • 7, CheckPrices
  • 8, Ok
  • 11, SentToInvoice. Not possible to update from this status
  • 15, ConfirmNoInvoice. Not possible to update from this status
  • 16, SuggestNoInvoice
  • 17, Pending. If updating from this status, the only valid status is "Ok"
  • 30, SentToCostProposal
  • 31, CostProposalApproved. If updating to this status, cost line must have "SentToCostProposal" as current status
  • 32, CostProposalRejeced. If updating to this status, cost line must have "SentToCostProposal" as current status
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:
  • Distance, integer format for Km.
  • Hours, TimeSpan type on decimal format. Where for example 1,00 means one hour and 1,50 means one hour and thirty minutes
  • Money, decimal format. Typically used when registering an expense in your local currency
  • Unit, integer format. Used to specify how many times a "fixed cost" expence has occured
SubContractor, InfoCare, PartnerIntegratorWithCostLine SubContractor, InfoCare, PartnerIntegratorWithCostLine

Requisition line fields

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:
  • 1 = Emergency
  • 3 = Normal
  • 4 = Refill
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
  • NotStarted
  • Ordered
  • Received
  • Delivered
  • ReceivedReturned
  • Returned
The part(s) is considered complete when parts(s) has reached "Returned". You cannot change this value directly as it is changed indirectly by applying a requisition function.
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

Attachments

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

Workflow history

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

User fields

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
Email 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

Serial Number History fields

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:
  • Part Number
  • Serial Number
  • TransactionDate
  • TransactionType
  • LifeStatus
  • Location
None None
The collection itself is accesible through the SerialNumberHistory property of the object returned by the method. None of these fields are updatable since they just correspond to historical information related to the given requisition.