Safran Documentation

Patch Codeset

22 Nov 2024
5 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Patch Codeset

Updated on 22 Nov 2024
5 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Patch Codeset

/v1/codesets

Maintain Codeset

Example for calling:

http://server/v1/codesets
http://server/v1/codesets?owner=safransa

Request Body = {….} see request fields below

Allowed methods:

[PATCH]

API Controller: codeset

Description:

Update the single codeset with the details provided; all other details remain as is. The codeset must be present, as must the resources which are to be patched. Should the codeset ID be missing, API will attempt to identify the codeset using the name and owner. API will only allow to patch one codeset per call; it will accept to patch 0, 1 or many field types. Some details are not possible to patch. It is possible to add new field types if the given details do not already exist.

Parameters:

Name	Type	Description	Notes
id	integer	Codeset ID
network_id	integer	Network ID	Mandatory when "SafranWebApiOwnerVerificationDuringApiCalls" is in use.
owner	string	Owner of the code set	Relates to "SafranWebApiOwnerVerificationDuringApiCalls" in "Application Settings".

Combining id with network_id is not supported
When "SafranWebApiOwnerVerificationDuringApiCalls" is in use, the Codeset retrieved can only be linked to projects owned by the same owner as the Codeset. Should the Codeset be linked to other projects, owned by others, the API will return failure.
Id will be used to identify the code set; if missing, the combination of name and owner will be used.
It is not possible to patch a field linked to another set.
- Unless only patching these fields:
  - visible
  - enabled
  - inherit_label
- In the case of the patch with more than one field, where one field is prevented from being patched, the whole operation will be prevented.

Request Fields:

Syntax of the fields are similar to what is found when using GET /v1/codesets with additional elements, see codesets.

CodeSet

Name	Type	Description	Notes
RowId	Integer	Sequential number used in the communication with the API,which identifies a row in this request that lines up with the response.
id	integer	Id of the code set
name	string	Name of the codeset
Owner	string	Owner of the codeset
date_fields	generic_field[]	Collection of defined generic_field objects of type date	See codesets for details
reference_fields	reference_field[]	Collection of defined reference_field objects	See codesets for details
flag_fields	generic_field[]	Collection of defined generic_field objects of type flag	See codesets for details
decimal_fields	generic_field[]	Collection of defined generic_field objects of type decimal	See codesets for details
duration_fields	generic_field[]	Collection of defined generic_field objects of type duration	See codesets for details
text_fields	generic_field[]	Collection of defined generic_field objects of type text	See codesets for details
outline_codes	outline_code[]	Collection of defined outline_code objects	See codesets for details

When network_id is provided, and id is null or 0, API will attempt to get the id from the network identified with the given network_id.
When "SafranWebApiOwnerVerificationDuringApiCalls" as per "Application Settings" is in use, the Codeset must not exist in other networks.
Where id is missing, API will identify the Codeset using name and owner.
Reference fields only support simple reference types, not referencing other references.

Field Types:

The details can be altered using this API.

Name	Type	Description
reference_fields	reference_field[]	Collection of defined reference_field objects
text_fields	generic_field[]	Collection of defined generic_field objects of type text
date_fields	generic_field[]	Collection of defined generic_field objects of type date
flag_fields	generic_field[]	Collection of defined generic_field objects of type flag
decimal_fields	generic_field[]	Collection of defined generic_field objects of type duration
duration_fields	generic_field[]	Collection of defined generic_field objects of type decimal
outlinecode	outlinecode[]	Collection of defined outline_code objects

outlinecode

The outline codes can be inserted, deleted, moved and updated during the patch action.
It is possible to move an outline code from one parent to another within the same field number, provided that the new parent does not already have an outline code with the same short value.
Inserting new outlinecode is possible as long as the new short value is not already present for the same parent.
Moving or adding an outlinecode to a parent is possible as long as the new level depth does not go beyond the maximum allowed depth.
Deleting of a outlinecode is possible as long as it is unused, e.g. not present on an activitiy.
See outline_code[] response for more details.

Restriction:

The following details cannot be patched:

Name	Type	Description	Notes
id	integer	Unique CodeSet Id
name	string	Project name
owner	string	Owner (Username)
field_nr	integer	Reference field number.	Any field_nr in any field_types cannot be modified.
_short	string	Reference value short identifier	The _short value of reference_values for a reference_field cannot be modified.

Response Fields:

Name	Type	Description	Notes
Config_Id	Integer	Configuration identification
RowId	Integer	Lines up with the RowId in Request Fields
Result	String	Indicate the success or failure of the action	S = success, F = failure

Sample Call Patch

json result

[
   {
      "RowId":1,
      "name":"UserfieldSets 002",
      "owner":"SAFRANSA",
      "reference_fields":[
         {
            "reference_values":[
               {
                  "description":"Reference 2.1, short 02.1",
                  "_short":"Short 02.1",
                  "sort_field":2
               },
               {
                  "description":"Reference 2.2, short 02.2",
                  "_short":"Short 02.2",
                  "sort_field":3
               }
            ],
            "field_nr":2,
            "label":"Reference 2**",
            "visible":true,
            "enabled":true
         }
      ]
   }
]

Sample Call Patch (Insert new top node)

json input to the API

[
  {
    "rowId": 1,
    "codeSetAction": "C",
    "updateIfExists": true,
    "id": 100011,
    "name": "Api Test Patch",
    "owner": "SAFRANSA",
    "outline_codes": [
      {
        "field_nr": 3,
        "outline_values": [
          {
            "description": "Top level node",
            "_short": "001",
            "seq": 0
          }
        ]
      }
    ]
  }
]

Sample Call Patch (Add new, alter description for existing and move to a new parent)

json input to the API

[
   {
      "RowId":1,
      "CodeSetAction":"C",
      "UpdateIfExists":true,
      "outline_codes":[
         {
            "oc_levels":3,
            "outline_values":[
               {
                  "description":"New item",
                  "_short":"O1-P0-S1§O1-P1-S2§O1-P2-S5",
                  "seq":0,
                  "level":3,
                  "delimiter_char":"§"
               },
               {
                  "description":"B.Update item",
                  "_short":"O1-P0-S1§O1-P1-S2.NewShort",
                  "seq":2,
                  "parent_seq":1,
                  "delimiter_char":"§"
               },
               {
                  "description":"C.Moved Item to P1",
                  "_short":"O1-P0-S1§O1-P1-S3",
                  "seq":3,
                  "parent_seq":1,
                  "delimiter_char":"§"
               }
            ],
            "field_nr":1,
            "label":"API Test.O1 Master",
            "inherit_label":false,
            "visible":true,
            "enabled":true
         }
      ],
      "id":100011,
      "name":"Api Test Patch",
      "owner":"SAFRANSA"
   }
]

Sample Call Patch (Move one outline code)

json input to the API

[
   {
      "RowId":1,
      "CodeSetAction":"U",
      "UpdateIfExists":false,
      "outline_codes":[
         {
            "oc_levels":3,
            "outline_values":[
               {
                  "description":"Description G, Can be moved",
                  "_short":"O1-P1-S2§O1-P1-S4",
                  "newparent_short":"O1-P0-S1",
                  "seq":0,
                  "delimiter_char":"§"
               }
            ],
            "field_nr":1,
            "label":"API Test.O1 Master",
            "inherit_label":false,
            "visible":true,
            "enabled":true
         }
      ],
      "id":100011,
      "name":"Api Test Patch",
      "owner":"SAFRANSA"
   }
]

Sample Call Patch (Delete using seq and another using short)

json input to the API

[
   {
      "RowId":1,
      "CodeSetAction":"D",
      "UpdateIfExists":false,
      "outline_codes":[
         {
            "oc_levels":3,
            "outline_values":[
               {
                  "_short":"",
                  "seq":1,
               },
               {
                  "_short":"O2-P0-S3",
                  "seq":0,
                  "delimiter_char":"§"
               }
            ],
            "field_nr":2,
            "label":"API Test.O1 Master",
            "inherit_label":false,
            "visible":true,
            "enabled":true
         }
      ],
      "id":100011,
      "name":"Api Test Patch",
      "owner":"SAFRANSA"
   }
]

Was this article helpful?

What's Next

Get UserFieldSet simple

Table of contents