Creating organizational units in SoftExpert Administration: Creation, update and deletion with SOAP web services

info

This tutorial aims to provide a brief demonstration on how you can build an application to create an organizational structure hierarchically in SoftExpert Administration. It is not a thorough guide on integrations, but rather a practical illustration for request creation.

Introduction

In order to create or update organizational units in SoftExpert Administration, you need to use our SOAP web services. There are three available methods for inserting, editing or deleting data referring to a department or business unit: newDepartment, editDepartment and deleteDepartment.

The newDepartment method allows inserting the data of a department or business unit, whereas the editDepartment method allows editing the data of an existing department or business unit. In its turn, the deleteDepartment method allows deleting a department or business unit.

Creating departments or business units

In this article, we will create departments and business units hierarchically, so they must be added by level. For example, in order to create a parent business unit and a child department for that business unit, you will need to do it in two steps. First, create the parent business unit using the newDepartment method; then, create the child department using the same method and entering the ID # of the parent business unit as parameter.

tip

Before creating a department or business unit, it is important to check whether it has already been recorded in SoftExpert Suite. A suggestion is to send a request to the editDepartment method and try editing the existing record. If the response is negative, the next action of the application may be to create the department or business unit using the newDepartment method.

SoftExpert Administration will not create duplicate records within departments or business units in the system. If a department or business unit exists already, its information can be updated through the editDepartment method, whereas new departments or business units must be created through the newDepartment method.

Resource URL

POST /apigateway/se/ws/adm_ws.php

Example

Creating a business unit

In this example, we are sending a request to the SoftExpert Administration endpoint in order to create a business unit. The parameters used in this request include:

Attributes used in this example:

Parameter	Type	Required	Description
ID	String	Yes	Business unit ID #
DESC	String	Yes	Business unit name
FGDEPTTYPE	Integer	Yes	Department type: 2 - Business unit.

Request example:

curl 'https://my-domain.softexpert.com/apigateway/se/ws/adm_ws.php' \
-H 'Content-Type: text/xml; charset=utf-8' \
-H 'SOAPAction: urn:admin#newDepartment' \
-H 'Authorization: <your_api_token>' \
-d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:admin">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:newDepartment>
         <urn:ID>BU001</urn:ID>
         <urn:DESC>Global Electronics Corporation</urn:DESC>
         <urn:FGDEPTTYPE>2</urn:FGDEPTTYPE>
      </urn:newDepartment>
   </soapenv:Body>
</soapenv:Envelope>' -X POST

Example for business unit creation response:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <newDepartmentResponse xmlns="urn:admin">
            <return>65</return>
            <Status>SUCCESS</Status>
            <Detail>Record(s) inserted</Detail>
            <Code>1</Code>
        </newDepartmentResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Creating a department

After successfully creating the business unit, use the ID # entered in the previous request example to link the department that will be created in this step to the business unit that has been created.

Attributes used in this example:

Parameter	Type	Required	Description
ID	String	Yes	Business unit ID #
DESC	String	Yes	Business unit name
FGDEPTTYPE	Integer	Yes	Department type: 2 - Business unit.

Request example:

curl 'https://my-domain.softexpert.com/apigateway/se/ws/adm_ws.php' \
-H 'Content-Type: text/xml; charset=utf-8' \
-H 'SOAPAction: urn:admin#newDepartment' \
-H 'Authorization: <your_api_token>' \
-d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:admin">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:newDepartment>
         <!--You may enter the following 6 items in any order-->
         <urn:ID>CA101</urn:ID>
         <urn:DESC>Mobile Devices Division</urn:DESC>
         <urn:IDUPPER>BU001</urn:IDUPPER>
         <urn:FGDEPTTYPE>1</urn:FGDEPTTYPE>
      </urn:newDepartment>
   </soapenv:Body>
</soapenv:Envelope>' -X POST

Department creation response:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <newDepartmentResponse xmlns="urn:admin">
            <return>66</return>
            <Status>SUCCESS</Status>
            <Detail>Record(s) inserted</Detail>
            <Code>1</Code>
        </newDepartmentResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Error and exception treatment

When working with the newDepartment, editDepartment and deleteDepartment methods, the implementation of an adequate error and exception treatment is crucial. This will ensure that any error that occurs during the execution of SOAP requests is identified and treated accordingly. Common errors include incorrect parameters, authentication issues, or service unavailability.

Upon receiving a response from the server, check the <Status> field in the response. If the value is SUCCESS, the operation was successful. However, if the value is ERROR, check the <Detail> and <Code> fields to find more information about the cause of the error and take proper measures.

Related articles

• Installing and using curl
• newDepartment web service
• editDepartment web service
• deleteDepartment web service