The Users API allows users to Create, Update and Get information about User records in Fusion

Overview

he Users API will be created in Karmak Unity to allow 3rd Parties to Create, Update and Get information about users setup in the Fusion Business System.

POST

https://api.karmak.io/api/unity/{version}/unityapi/user/CreateUser

PUT

https://api.karmak.io/api/unity/{version}/unityapi/user/UpdateUser

GET

https://api.karmak.io/api/unity/{version}/unityapi/user/{username}

Specifications

GET

  • The GET method will be used to retrieve information about a specific User Record in Fusion.

  • The user will need to pass in the Username of the User record in Fusion they wish to return.

    • Provide the Fusion Username (without the brackets) where indicated above in the GET Request with the {username} to get information about the specific user.
  • The Response of the GET will include all the fields that are able to be passed in on the POST of the User API.

POST

  • The POST method will be used to create User Records in Fusion.

  • Only one User record will be allowed in a single request call.

  • The User Identity section will be ignored when creating a User

  • If the user chooses to create a User Branch Department record for the User record the Branch, Department and User Group must all be passed in and match valid values in Fusion.

  • Multiple User Branch Departments will be allowed to be created for a User.

  • If the User Branch Department record isn’t created, the User record created will not be allowed to login to Fusion.

  • If the User Name already exists in Fusion the record won’t be created.

  • A response will be provided with a message section that will outline a success or any issues that prevented the User from being created.

  • The Fusion Username used in the Unity API call will be used as the Add and Last Update User of the User created.

  • The Date and Time the Unity API call was made will be used as the Add Date and Last Update of the User created.

  • The User record will be created in Fusion following the standard create logic of the PMB90500 User and PMB90550 User Branch Department form in Fusion outside of any specific rules listed in this section and the POST/PUT Request Fields Section below.

  • The following fields will be set by default upon creating a User record

    • Language will be set to English

    • Search Record will be set to 50

    • Email Delivery will be set to SMTP

PUT

  • The PUT method will be used to update User Records in Fusion.

  • Only one User record will be allowed in a single request call.

  • Only fields that are expected to be updated should be passed in outside of the required fields.

  • In order to update an existing User record the user will be required to send in the User in the User Identity section to find a match. If a match isn’t found an update will not be performed.

  • In order to update an existing User Branch Department record on the User record the user will be required to send in the Branch and Department in the User Identify section that matches an existing User Branch Department record on the User record.

  • Only 1 Branch Department Record will be allowed to be sent in the BranchDepartmentList Node.

  • In order to Add or Remove a Branch Department Record on an existing User Record, don’t pass in the Branch and Department as part of the Identity, rather pass those values in on the BranchDepartmentList Node section and use the Action field to set whether you are looking to Add or Remove the Branch Department Record.

  • A response will be provided with a message section that will outline a success or any issues that prevented the User from being updated.

  • The Fusion Username used in the Unity API call will be used as the Last Update User of the User updated.

  • The Date and Time the Unity API call was made will be used as the Last Update Date of the User updated.

Request Fields

Field Field Type Required Length POST Business Rules and Defaults PUT Business Rules and Defaults
User Identity Node     This will be ignored in a POST This section will be used to identify the User that will be updated. If the User Branch Department information is being updated the Branch, Department and User Group must all be passed in and match an existing record for the User record.
UserName string Yes 20   This is the User Name that will be looked up in order to update information about the record.
Branch string Dependent 10   This is the Branch that will be looked up on the User Branch Department record of the User record to update
Department string Dependent 10   This is the Department that will be looked up on the User Branch Department record of the User record to update
Main Body          
UserName string Yes 20 This is the User Name to be created This is the User Name value that the record will be updated to.
Password string Yes 100 This is the Password of the User record that will be created. This is the Password value that will be updated on the User record.
FirstName string Yes 100 This is the First Name of the User record that will be created. This is the First Name value that will be updated on the User record.
LastName string Yes 100 This is the Last Name of the User record that will be created This is the Last Name value that will be updated on the User record.
IsInactive bit   1 This field will set the Inactive field on the User record. Set to True to identify the User as Inactive. The default will be False This field will set the Inactive field on the User record. Set to True to identify the User as Inactive. The default will be False
IsDisabled bit   1 This field will set the Disabled field on the User record. Set to True to identify the User as Disabled. Disabled is a state where the user can’t login but can be found in User VTL searches. The default will be false. This field will set the Disabled field on the User record. Set to True to identify the User as Disabled.Disabled is a state where the user can’t login but can be found in User VTL searches. The default will be false
DomainUsername string   20 This is the Domain Username that will be added to the User form in Fusion. This must match a valid Active Directory Username setup in the Customer ‘s Domain This field will update the Domain Username on the User record in Fusion. This must match a valid Active Directory Username setup in the Customer ‘s Domain
Email string   100 This is the Email Address of the User record on the User form in Fusion. This must be in a valid email address form. This field will update the Email Address of the User record on the User form in Fusion. This must be in a valid email address form.
CellPhone string   30 This is the Cell Phone field of the User being created. This is the Cell Phone field of the User being updated.
WorkPhone string   30 This is the Work Phone field of the User being created. This is the Work Phone field of the User being updated.
HomePhone string   30 This is the Home Phone field of the User being created. This is the Home Phone field of the User being updated.
Fax string   30 This is the Fax field of the User being created. This is the Fax field of the User being updated.
Pager string   30 This is the Pager field of the User being created. This is the Pager field of the User being updated.
BranchDepartmentList Node     This section will be used to identify User Branch Department records for the User record. Multiple User Branch Department Records will be created when a User is created. At least 1 User Branch Department record will be required for a user to login to Fusion but is not required to be sent in on the API. Only 1 User Branch Department record will be able to be updated on the PUT. The User Branch Department record that is updated will be the User Branch Department record in the Identity section.
Action string   5 This field will be ignored in the POST as it is used to identify whether to Add or Remove Branch Department records as part of the PUT This field will be used to identify whether the Branch, Department and User Group record in the BranchDepartmentList is being attempted to be added or removed from the User Record. Valid options are “Add” or “Remove”This field will only be used if the Branch and Department aren’t populated in the Identity Section. If the Branch and Department is identified in the Identity Section it is assumed the user is attempting to update that record with the information included in the BranchDepartmentList Node. If this field is passed in with a value of “Add” then a valid Branch, Department and User Group must be passed in the BranchDepartmentList Node that doesn’t exist for the User. This record would be added to the User. If it does exist a user will be provided with a warning saying the record wasn’t added. If this field is passed in with a value of “Remove” then a valid Branch and Department must be passed in the BranchDepartmentList Node that exists for the User. This record will be looked up and deleted from the User record. If it doesn’t exist a user will be provided with a warning saying the record wasn’t found and the update continues
Branch string Dependent 10 This is the Branch the User Branch Department record will be created for. This must match a valid Branch Code in Fusion. The Branch, Department and User Group must all be passed in to create a Branch Department record. This is the Branch value the User Branch Department record will be updated with.This must match a valid Branch Code in Fusion.
Department string Dependent 10 This is the Department the User Branch Department record will be created for. This must match a valid Department in FusionThe Branch, Department and User Group must all be passed in to create a Branch Department record. This is the Department value the User Branch Department record will be updated with.This must match a valid Department in Fusion.
UserGroup string Dependent 50 This is the User Group the User Branch Department record will be created for. This must match a valid User Group in Fusion. The Branch, Department and User Group must all be passed in to create a Branch Department record. This is the User Group value the User Branch Department record will be updated with.This must match a valid User Group in Fusion.
IsDepartmentAdministrativeUser bit   1 This is the Department Administrative User checkbox of the User Branch Department record. If this isn’t passed in it will be set to falseIf the Branch Administrative User is passed in as True this will be ignored and set to True If this value isn’t passed in no change will be made. If the Branch Administrative User is passed in as True this will be ignored and set to True
IsBranchAdministrativeUser bit   1 This is the Branch Administrative User checkbox of the User Branch Department record. If this isn’t passed in it will be set to falseIf this is set to True then the Department Administrative User will be ignored and set to True If this value isn’t passed in no change will be madeIf this is passed in as True then the Branch Administrative User will be ignored and set to True.
IsDivisionAdministrativeUser bit   1 This is the Division Administrative User checkbox of the User Branch Department record. If this isn’t passed in it will be set to falseIf the Enterprise or Corporate Administrative User is passed in as True this will be ignored and set to True If this value isn’t passed in no change will be made. If the Enterprise or Corporate Administrative User is passed in as True this will be ignored and set to True
IsCorporateAdministrativeUser bit   1 This is the Corporate Administrative User checkbox of the User Branch Department record. If this isn’t passed in it will be set to falseIf the Enterprise Administrative User is passed in as True this will be ignored and set to TrueIf this is set to True then the Division Administrative User will be ignored and set to True If this value isn’t passed in no change will be made. If the Enterprise Administrative User is passed in as True this will be ignored and set to True. If this is set to True then the Division Administrative User will be ignored and set to True.
IsEnterpriseAdministrativeUser bit   1 This is the Enterprise Administrative User checkbox of the User Branch Department record. If this isn’t passed in it will be set to falseIf this is set to True then the Corporate and Division Administrative User will be ignored and set to True If this value isn’t passed in no change will be made. If this is set to True then the Corporate and Division Administrative User will be ignored and set to True.
IsDefault bit   1 This will set the User Branch Department record to the Default if passed in as True. If passing in Multiple User Branch Department Records only one record should be set this value to True. If multiple records are passed in with this value to True then the last created record should be the default. If no records are passed in with this value set to True then the last created record should be the default. This will set the User Branch Department record to the Default if passed in as True. If this is passed in as True and the User Branch Department record being updated is not the Default, this will be set as the Default and the existing User Branch Department record will have the default field set to false.

GET Request and Response

api/unity/v1/unityapi/User/TechUser1
{
    "UserName": "TechUser1",
    "Password": null,
    "FirstName": "Tech1",
    "LastName": "User1",
    "IsInactive": false,
    "IsDisabled": false,
    "Email": "",
    "DomainUserName": null,
    "SearchRecordsReturned": 50,
    "EmailSettingType": "SMTP",
    "AddDate": "2020-07-28T00:36:40.167",
    "AddUser": "karmak",
    "UpdateUser": "karmak",
    "EmployeeNumber": null,
    "Language": "English",
    "LastUpdate": "2020-07-28T00:36:40.167",
    "BranchDepartmentList": [
        {
            "Branch": "01",
            "Department": "Service",
            "UserGroup": "System Administrator",
            "IsDepartmentAdministrativeUser": true,
            "IsBranchAdministrativeUser": true,
            "IsDivisionAdministrativeUser": true,
            "IsCorporateAdministrativeUser": true,
            "IsEnterpriseAdministrativeUser": true,
            "IsDefaultRecord": true,
            "Action": null
        }
    ],
    "WorkPhone": "",
    "HomePhone": "",
    "CellPhone": "",
    "Fax": "",
    "Pager": ""
}

POST Request - Multiple Branch Department Records

{
    "UserName": "spool_Unity4",
    "Password": "unity",
    "FirstName": "Stephanie",
    "LastName": "Pool",
    "BranchDepartmentList": [
        {
            "Branch": "01",
            "Department": "service",
            "UserGroup": "System Administrator",
            "IsDepartmentAdministrativeUser": true,
            "IsBranchAdministrativeUser": false,
            "IsDivisionAdministrativeUser": true,
            "IsCorporateAdministrativeUser": true,
            "IsEnterpriseAdministrativeUser": true,
            "IsDefaultRecord": false
        },
        {
            "Branch": "01",
            "Department": "Parts",
            "UserGroup": "System Administrator",
            "IsDepartmentAdministrativeUser": false,
            "IsBranchAdministrativeUser": true,
            "IsDivisionAdministrativeUser": true,
            "IsCorporateAdministrativeUser": true,
            "IsEnterpriseAdministrativeUser": true,
            "IsDefaultRecord": false
        }
    ]
}

POST Response

{
    "Status": "Succesfully created user.",
    "Message": null
}

PUT Request - Update Branch Department Record

{
    "Identity": {
        "Branch": "01",
        "Department": "service",
        "UserName": "dpool_Unity"
    },
    "BranchDepartmentList": [
        {
            "IsEnterpriseAdministrativeUser": true,
            "IsDivisionAdministrativeUser":false,
	       	"IsCorporateAdministrativeUser":false
        }
    ]
}

PUT Response

{
    "Status": "User updated.",
    "Message": null
}

PUT Request - Add Branch Department Record

{
    "Identity": {
        "UserName": "TechUser13"
    },

        "BranchDepartmentList": 
    [
        {
            "Branch": "01",
            "Department":"Service",
            "UserGroup":"System Administrator",
            "IsBranchAdministrativeUser":true,
            "IsEnterpriseAdministrativeUser":true,
            "Action":"Add"
        }
    ]
}

PUT Response

{
    "Status": "User updated.",
    "Message": null
}

PUT Request - Remove Branch Department Record

{
    "Identity": {
        "UserName": "ffbob38"
    },

        "BranchDepartmentList": 
    [
        {
              "Branch": "Cambridge",
              "Department":"Parts",
              "Action":"Remove"
        }
    ]
}

PUT Response

{
    "Status": "User updated.",
    "Message": null
}