Overview of interface
Web service is used in updating the list of projects provided in the request into Nepton. If the project exists in Nepton, its information will be updated. Project to update will be identified by either its Nepton identifier (Id), the identifier defined in ExistingIdentifier-element or with project code (Code). Project managers for a project can be updated by providing a ProjectManagers - element under that project containing ProjectManager - elements for each project manager to update. ProjectManager - element identifies the project manager by either personnel number (PersonnelNumber), username (Username) or Nepton internal identifier for the user (UserId). Updating of project managers can be done so that the project managers provided in the request are added to Nepton in addition to project managers set earlier in Nepton (default) or updating will remove project managers set earlier in Nepton, if they are not provided in the request as project managers, by adding RemoveOthers - element with a value of true inside that projects ProjectManagers - element.
Web service WSDL-schema is available publicly here. Interfaces are described generally here.
Occurrences - column in request description defines whether a field is mandatory in a request or not. 0 occurrences means that field is not mandatory in the request. 1 occurrence means that the field must be present in the request once. 0..n occurrences means that the request may contain any number of those fields or none at all. Occurrences 1..n means that the request may contain any number of those fields but there must be at least one instance of that field.
Changes to earlier version (EnsureProjectsExistV3)
Structural changes
| Old | New | Information |
|
|
Root element name in request has changed |
|
|
Root element name in response has changed |
New properties and elements
-
Project managers can be defined for a project by providing the project manager's external identifier
- PersonExternalIdentifier - element added to the request under ProjectManagers
- PersonExternalIdentifier - element contains elements Identifier and FieldName
- PersonExternalIdentifier - element added to the request under ProjectManagers
Request data
| LEVEL | FIELD NAME | TYPE | OCCURRENCES | DESCRIPTION |
|---|---|---|---|---|
| Root, under SOAP body | ParametersForEnsureProjectsExistV3 | XML element | 1 | |
| 1 | CallerAuthentication | XML element | 1 | More information about authentication here |
| 1 | ProjectList | XML element | 1 | List of projects |
| 2 | Project | XML element | 1..n | Information for a project. Information about common element content can be seen here. |
| 3 | ExistingProjectIdentifier | XML element | 0..1 | Identifier for fetching existing project identifier. If project is found, its information will be updated, otherwise a new project will be created. The identifier given in this element is not saved into project information. |
| 4 | Identifier | string | 1 | Value of project identifier. |
| 4 | IdentifierType | string | 1 |
Project identifier type. Can be either
Read more about project code and external identifier here. |
| 3 | Id | unsignedInt | 0..1 | Nepton unique identifier for project. Define only if you want Nepton to identify the existing project based in this information. |
| 3 | ExternalIdentifier | XML element | 0..n | Identifier from an external system which is saved as the project's external identifier. |
| 4 | Identifier | string | 1 | Value of project identifier. Character limit 64 characters. |
| 4 | IdentifierType | string | 1 |
Project identifier type. At the moment only supported value is
Read more about external identifier here. |
| 3 | Name | string | 1 | Project name. Character limit 255 characters. |
| 3 | Deleted | boolean | 0..1 | Is project deleted or not. Deleted projects are saved in the database, but restoring them is not possible via this API. |
| 3 | Active | boolean | 0..1 |
If set to If |
| 3 | Code | string | 0..1 | Project code. If ID or ExistingIdentifier - elements are not defined in the request, identifying existing project will be attempted by the value of this field. Character limit 255 characters. |
| 3 | TypeInternalName | string | 0..1 |
Project type internal identifier. Must be set when creating a project. If now separate project types are set, value is Character limit 190 characters. |
| 3 | Description | string | 0..1 | Project description |
| 3 | StartDate | date | 0..1 |
Project begin date. Project can't be targeted in events or have its hours reported before this date. Value can also be
|
| 3 | EndDate | date | 0..1 |
Project start date. Project can't be targeted in events or have its hours reported after this date. Value can also be
|
| 3 | ParentProjectId | unsignedInt | 0..1 |
Nepton unique identifier for the parent project of the project. Value can also be
|
| 3 | ParentProjectCode | string | 0..1 |
Project code for the parent project of the project. Value can also be
|
| 3 | ParentProjectIdentifier | XML element | 0..1 |
Identifier for the parent project of the project. Value can also be
|
| 4 | Identifier | string | 1 | Identifier for the parent project |
| 4 | IdentifierType | string | 1 | Parent project identifier type. Can be eitherProjectCode or ExternalIdentifier
|
| 3 | ChildProjects | XML element | 0..n | Not used |
| 3 | ProjectManagers | XML element | 0..1 | Project managers to be updated for the project |
| 4 | RemoveOthers | boolean | 0..1 | If set as true, removes existing project managers from the project if they are not set as project managers in the request |
| 4 | ProjectManager | XML element | 0..n | Project manager to be updated for the project |
| 5 | UserId | unsignedInt | 0..1 | Nepton unique user identifier of person |
| 5 | Username | string | 0..1 | Username of person |
| 5 | PersonnelNumber | string | 0..1 | Personnelnumber of person |
| 5 | PersonExternalIdentifier | XML element | 0..1 | External identifier information of person |
| 6 | Identifier | string | 1 | External identifier value |
| 6 | FieldName | string | 1 |
External identifier field name. Supported values: ExternalIdentifier1 |
Example request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tyo="http://tyoaika.tyoteho.fi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header/>
<soapenv:Body>
<tyo:ParametersForEnsureProjectsExistV3>
<CallerAuthentication /> <!-- Authentication is required but is omitted from this example -->
<ProjectList>
<Project>
<ExistingProjectIdentifier>
<Identifier>4a78611d-4a00-4c4a-a987-865664d732ce</Identifier>
<IdentifierType>ExternalIdentifier</IdentifierType>
</ExistingProjectIdentifier>
<ExternalIdentifier>
<Identifier>4a78611d-4a00-4c4a-a987-865664d732ce</Identifier>
<IdentifierType>ExternalIdentifier</IdentifierType>
</ExternalIdentifier>
<Name>Projekti X</Name>
<Code>1000/9001</Code>
<TypeInternalName>project_work</TypeInternalName>
<Description>Lorem ipsum primis venenatis justo mollis fringilla lectus sociosqu nostra, vehicula nunc massa sodales habitasse duis</Description>
<StartDate>2001-01-01</StartDate>
<EndDate xsi:nil="true" />
<ParentProjectIdentifier>
<Identifier>45453ddd-f167-408b-9e75-6c419755caf8</Identifier>
<IdentifierType>ExternalIdentifier</IdentifierType>
</ParentProjectIdentifier>
<ProjectManagers>
<RemoveOthers>true</RemoveOthers>
<ProjectManager>
<PersonnelNumber>27</PersonnelNumber>
</ProjectManager>
<ProjectManager>
<UserName>Example Username</PersonnelNumber>
</ProjectManager>
<ProjectManager>
<PersonExternalIdentifier>
<Identifier>MGR-12345</Identifier>
<FieldName>ExternalIdentifier1</FieldName>
</PersonExternalIdentifier>
</ProjectManager>
</ProjectManagers>
</Project>
</ProjectList>
</tyo:ParametersForEnsureProjectsExistV3>
</soapenv:Body>
</soapenv:Envelope>
Response
| TASO | KENTÄN NIMI | MUOTO | ESIINTYMISKERRAT | SELITE |
|---|---|---|---|---|
| Root, under SOAP body | ReturnValueForEnsureProjectsExistV3 | XML element | 1 | |
| 1 | ResponseCode | integer | 1 | Response code of handling the request. List of response codes can be found here. |
| 1 | ResponseString | string | 1 | Response description |
| 1 | EnsureProjectsExistResultList | XML element | 1 | |
| 2 | EnsureProjectsExistResult | XML element | 0..n | Result of handling a project |
| 3 | ResponseCode | integer | 1 | Response code of handling the project. List of response codes can be found here. |
| 3 | ResponseString | integer | 1 | Response description |
| 3 | ProjectId | unsignedInt | 1 |
Nepton unique identifier for handled project. Can also be
In error situations |
| 3 | ProjectIdentifier | XML element | 1 | Identifier that was sent in theExistingProjectIdentifier field. |
| 4 | Identifier | string | 1 | Value of the project identifier |
| 4 | IdentifierType | string | 1 |
Project identifier type. Can be either
Read more about project code and external identifier here. |
| 3 | ProjectManagers | XML element | 0..1 | Project project managers. Is returned only if ProjectManagers - element was present in the request. |
| 4 | ProjectManager | XML element | 0..n | Project project manager |
| 5 | UserId | unsignedInt | 0..1 | Nepton unique user identifier of person |
| 5 | Username | string | 0..1 | Username of person |
| 5 | PersonnelNumber | string | 0..1 | Personnelnumber of person |
| 5 | PersonExternalIdentifier | XML element | 0..1 | External identifier information of person |
| 6 | Identifier | string | 1 | External identifier value |
| 6 | FieldName | string | 1 |
External identifier field name. Supported values: ExternalIdentifier1 |
Example response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tyo="http://tyoaika.tyoteho.fi">
<SOAP-ENV:Body>
<tyo:ReturnValueForEnsureProjectsExistV4>
<ResponseCode>1000</ResponseCode>
<ResponseString>All clear. No errors.</ResponseString>
<EnsureProjectsExistResultList>
<EnsureProjectsExistResult>
<ResponseCode>1000</ResponseCode>
<ResponseString>All clear. No errors.</ResponseString>
<ProjectId>76254</ProjectId>
<ProjectIdentifier>
<Identifier>4a78611d-4a00-4c4a-a987-865664d732ce</Identifier>
<IdentifierType>ExternalIdentifier</IdentifierType>
</ProjectIdentifier>
<ProjectManagers>
<ProjectManager>
<UserId>09876543210</UserId>
<UserName>Test User</UserName>
<PersonnelNumber>27</PersonnelNumber>
<PersonExternalIdentifier>
<Identifier>MGR-010101</Identifier>
<FieldName>ExternalIdentifier1</FieldName>
</PersonExternalIdentifier>
</ProjectManager>
<ProjectManager>
<UserId>1234567890</UserId>
<UserName>Example Username</PersonnelNumber>
<PersonnelNumber>1274</PersonnelNumber>
<PersonExternalIdentifier>
<Identifier>MGR-67890</Identifier>
<FieldName>ExternalIdentifier1</FieldName>
</PersonExternalIdentifier>
</ProjectManager>
<ProjectManager>
<UserId>0234567890</UserId>
<UserName>Other example</PersonnelNumber>
<PersonnelNumber>12714</PersonnelNumber>
<PersonExternalIdentifier>
<Identifier>MGR-12345</Identifier>
<FieldName>ExternalIdentifier1</FieldName>
</PersonExternalIdentifier>
</ProjectManager>
</ProjectManagers>
</EnsureProjectsExistResult>
</EnsureProjectsExistResultList>
</tyo:ReturnValueForEnsureProjectsExistV4>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>