/icws/{sessionId}/configuration/roles

GET

/icws/{sessionId}/configuration/roles

Retrieves a list of roles. The results can be filtered by specifying a query. All list-based configuration object resources will have a complex property that will serve as its identity. This property is called the configurationId and consists of a {id, displayName, uri}.

The following result limits are enforced by the server regardless of the value of the Range header field:

  • If no properties are included (see select parameter), then all of the items will be returned.
  • If any properties are included (see select parameter), then a maximum of 200 items will be returned in the result.
Feature Version
configuration 1

Request

Parameters
Type
Name
Comments
Header
ININ-ICWS-CSRF-Token

Required

The ININ session token necessary for all calls that require a security or user context.

    Header
    Cookie

    Required

    The session cookie. With the exception of the connection request, all requests must provide a session cookie.

      Template
      sessionId

      Required

      The ININ session ID necessary for all calls that require a security or user context.

        Header
        Range

        Specifies the range of results to be returned.

        Example: Range: items=10-20.

          Query
          select

          A comma-delimited list of fields to include in the query. If no fields are specified, then only the ID of the items is returned.

          Example: select=extension,defaultWorkstation

          One can also specify that all of the properties should be returned by using the '*' wildcard value. This is a shortcut for specifying all of the properties' names in the parameter.

          The selected properties with a NULL value will not be returned to conserve the Interaction Center server's resources.

            Query
            where

            A comma-delimited list of conditions to filter the results of the query. Only items that satisfy all conditions will be returned.

            The following operators can be used:

            • eq - equals
            • sw - starts with
            • ct - contains

            Example: where=configurationId.id sw Value

            It is supported for the following properties:

            • configurationId.displayName
            • configurationId.id
            • notes

              Query
              orderBy

              The name of the field to sort the results by and an optional sort direction. The default is to sort by configurationId.displayName in ascending order. A query can only be sorted by one field and only supports one (optional) direction indicator: asc (ascending) or desc (descending).

              To sort in descending order use: orderBy=configurationId.id desc

              To sort in ascending order use: orderBy=configurationId.id (or orderBy=configurationId.id asc)

              It is supported for the following properties:

              • configurationId.displayName
              • configurationId.id

              Default value: configurationId.displayName

                Query
                rightsFilter
                The security right to use when filtering the results.

                Default value: admin

                Options:

                • view
                • admin

                Query
                actualValues
                When set to true, this flag indicates that the actual values for inheritable data types should be returned in addition to the other requested data.

                Default value: false

                  Query
                  inheritedValues
                  When set to true, this flag indicates that the inherited values for inheritable data types should be returned in addition to the other requested data.

                  Default value: false

                    Response

                    200 - OK
                    The result set of the query is included in the response.
                    Parameters
                    Type
                    Name
                    Comments
                    Header
                    Content-Range

                    Required

                    Specifies the range of items being returned in the result along with the total number of items.

                    Example: Content-Range: items 5-10/200

                      roles
                      Represents a list of role configuration objects.
                      Property
                      Value
                      Comments
                      id
                      String

                      Required

                      The unique identifier used to reference this configuration object.
                      displayName
                      String
                      The display name of this configuration object.

                      This property can be null.

                      uri
                      Uri
                      A URI used to access this configuration object.
                      createdDate
                      DateTime
                      The date this configuration object was created.

                      This is a read only property and can not be changed with PUT or POST operations.

                      This property can be null.

                      name
                      String

                      Required

                      The key identifying this pair.
                      value
                      String

                      Required

                      The value of this pair.

                      This property can be null.

                      lastModifiedDate
                      DateTime
                      The date this configuration object was last modified.

                      This is a read only property and can not be changed with PUT or POST operations.

                      This property can be null.

                      notes
                      String
                      The notes for this configuration object.

                      This property can be null.

                      id
                      String
                      The unique identifier used to reference this configuration object. The value of this can be null when the grouping of this value is All. Otherwise, it is required.

                      This property can be null.

                      displayName
                      String
                      The display name of this configuration object.

                      This property can be null.

                      uri
                      Uri
                      A URI used to access this configuration object.

                      This property can be null.

                      none
                      0
                      Represents no object type.
                      acg
                      1
                      Represents an ACG object type.
                      workgroup
                      2
                      Represents the workgroup object type.
                      lineGroup
                      3
                      Represents the lineGroup object type.
                      feedbackSurveyGroup
                      4
                      Represents the feedbackSurveyGroup object type.
                      all
                      0
                      Represents all possible ConfigurationIds.
                      single
                      1
                      Represents a single ConfigurationId.
                      group
                      2
                      Represents a grouping of ConfigurationIds where each ConfigurationId is a member of some other Aggregate (Workgroup, Role, ...).
                      none
                      0
                      The property was not inherited.
                      Workgroup
                      1
                      The property was inherited from a Workgroup configuration object.
                      Role
                      2
                      The property was inherited from a Role configuration object.
                      DefaultUser
                      3
                      The property was inherited from the Default User configuration object.
                      ClientConfigurationTemplate
                      4
                      The property was inherited from a Client Configuration Template configuration object.
                      actualValue
                      Boolean
                      The value directly assigned to this configuration object. This value is required for POST and PUT operations.

                      This property can be null.

                      effectiveValue
                      Boolean
                      The effective value of this property, from the blending of the actualValue with the inheritedValue. This value is required for GET object and GET object list operations.

                      This property can be null.

                      inheritedValue
                      Boolean
                      The actual inherited value, based on this configuration object's membership/inheritance, such as Workgroup, Role, and Default User.

                      This property can be null.

                      none
                      0
                      The property was not inherited.
                      Workgroup
                      1
                      The property was inherited from a Workgroup configuration object.
                      Role
                      2
                      The property was inherited from a Role configuration object.
                      DefaultUser
                      3
                      The property was inherited from the Default User configuration object.
                      ClientConfigurationTemplate
                      4
                      The property was inherited from a Client Configuration Template configuration object.
                      values
                      Boolean

                      Required

                      400 - Bad Request
                      Invalid parameter value was specified.

                      Error Responses

                      Error Identifier
                      Error Type
                      Error Description
                      error.request.invalidRepresentation.malformed
                      Type: urn:inin.com:common:error
                      The request representation object was malformed.
                      Feature Version
                      configuration 2
                      error.request.configuration.get.selectAll
                      Type: urn:inin.com:common:error
                      Combining the wildcard (*) and one or more specific properties in one request is not supported.
                      Feature Version
                      configuration 2
                      error.request.configuration.getObjectList
                      Type: urn:inin.com:configuration:getObjectListError
                      One or more of the properties in the 'rightsFilter', 'select', 'where', or 'orderBy' query parameters are not supported.
                      Feature Version
                      configuration 2
                      error.request.configuration.getObjectList.invalidSortDirection
                      Type: urn:inin.com:common:error
                      The sort direction in the 'orderBy' query parameter is not supported.
                      Feature Version
                      configuration 2
                      error.request.configuration.getObjectList.invalidWhereOperator
                      Type: urn:inin.com:common:error
                      The operator in the 'where' query parameter is not supported.
                      Feature Version
                      configuration 2
                      error
                      Provides additional detail for an error.
                      Property
                      Value
                      Comments

                      Multiple options:

                      The value can be assigned any of the following options.
                      errorId
                      String
                      The error identifier that describes the current error.
                      message
                      String

                      Required

                      A message that describes the current error.
                      __type
                      "urn:inin.com:configuration:getObjectListError"

                      Required

                      The JSON type representing this option.
                      errorId
                      String
                      The error identifier that describes the current error.
                      message
                      String

                      Required

                      A message that describes the current error.
                      select
                      List [Unbounded]: String
                      The properties in the select query parameter that are not supported by the object type.

                      Property type documentation:

                      Represents a collection of strings.

                      rightsFilter
                      String
                      The properties in the rightsFilter query parameter that are not supported by the object type.
                      where
                      List [Unbounded]: String
                      The properties in the where query parameter that are not supported by the object type.

                      Property type documentation:

                      Represents a collection of strings.

                      orderBy
                      String
                      The property in the orderBy query parameter is not supported by the object type.
                      500 - Internal Server Error
                      An unexpected error occurred while processing the request.

                      Error Responses

                      Error Identifier
                      Error Type
                      Error Description
                      error.request.internalServerError
                      Type: urn:inin.com:common:error
                      The server encountered an unexpected, internal error.
                      Feature Version
                      configuration 2
                      error.request.timeout
                      Type: urn:inin.com:common:error
                      The request timed out.
                      Feature Version
                      configuration 2
                      error
                      Provides additional detail for an error.
                      Property
                      Value
                      Comments
                      errorId
                      String
                      The error identifier that describes the current error.
                      message
                      String

                      Required

                      A message that describes the current error.
                      401 - Unauthorized
                      The specified session token is missing, invalid, or has expired.
                      Parameters
                      Type
                      Name
                      Comments
                      Header
                      WWW-Authenticate

                      Required

                      Indicates that the client needs to authenticate using a custom ICWS scheme, which supports a realm of type ICWS and a location which is the URL at which the client can authenticate. A typical example would be the following.

                      WWW-Authenticate: ICWS realm="ICWS" location="/ICWS/connection"

                        error
                        Provides additional detail for an error.
                        Property
                        Value
                        Comments
                        errorId
                        String
                        The error identifier that describes the current error.
                        message
                        String

                        Required

                        A message that describes the current error.
                        410 - Gone
                        This resource has been deprecated and removed from the API.
                        error
                        Provides additional detail for an error.
                        Property
                        Value
                        Comments
                        errorId
                        String
                        The error identifier that describes the current error.
                        message
                        String

                        Required

                        A message that describes the current error.

                        POST

                        /icws/{sessionId}/configuration/roles

                        Creates a new role resource.
                        Feature Version
                        configuration 1

                        Request

                        Parameters
                        Type
                        Name
                        Comments
                        Header
                        ININ-ICWS-CSRF-Token

                        Required

                        The ININ session token necessary for all calls that require a security or user context.

                          Header
                          Cookie

                          Required

                          The session cookie. With the exception of the connection request, all requests must provide a session cookie.

                            Template
                            sessionId

                            Required

                            The ININ session ID necessary for all calls that require a security or user context.

                              Header
                              ININ-ICWS-Transaction-Id
                              The transaction ID for grouping the server-side rights calculation for several configuration requests.
                              Feature Version
                              configuration 11

                                Representations
                                role
                                Represents the role configuration object.
                                Property
                                Value
                                Comments
                                createdDate
                                DateTime
                                The date this configuration object was created.

                                This is a read only property and can not be changed with PUT or POST operations.

                                This property can be null.

                                name
                                String

                                Required

                                The key identifying this pair.
                                value
                                String

                                Required

                                The value of this pair.

                                This property can be null.

                                lastModifiedDate
                                DateTime
                                The date this configuration object was last modified.

                                This is a read only property and can not be changed with PUT or POST operations.

                                This property can be null.

                                notes
                                String
                                The notes for this configuration object.

                                This property can be null.

                                Response

                                201 - Created
                                The request to create the role was acknowledged. The new object will be available shortly depending on the server's load. The ID provided in the request's body is returned in the response.
                                updateOperationResult
                                Represents the result from a put or post operation.
                                Property
                                Value
                                Comments
                                id
                                String

                                Required

                                The unique identifier used to reference this configuration object.
                                uri
                                Uri
                                A URI used to access this configuration object.
                                setOK
                                0
                                Setting the license succeeded. This value is never sent.
                                setWarningExceedsThreshold
                                1
                                Indicates that a dynamic license was found with an assignment count that exceeds it's assignable and or concurrent thresholds. As this is only a warning to indicate problems, the license in the request was set successfully.
                                setErrorExceedsThreshold
                                2
                                Indicates that a dynamic license being set exceed it's assignable or concurrent thresholds and was not set as a result. This can be returned for any license assigned to a user or station as part of setting it's licenses because they are all checked for problems as part of the operation.
                                setWarningMissingQualifiers
                                3
                                Indicates that the ACD media level in the request did not have a corresponding set of ACD media types and the default value(s) for the level were set as a result.
                                400 - Bad Request
                                Invalid request was provided. If validation errors exist, they will be returned in the response.

                                Error Responses

                                Error Identifier
                                Error Type
                                Error Description
                                error.request.invalidRepresentation.malformed
                                Type: urn:inin.com:common:error
                                The request representation object was malformed.
                                error.request.configuration.update
                                Type: urn:inin.com:configuration:configurationError
                                The request has one or more license or validation errors in it.
                                error
                                Provides additional detail for an error.
                                Property
                                Value
                                Comments

                                Multiple options:

                                The value can be assigned any of the following options.
                                errorId
                                String
                                The error identifier that describes the current error.
                                message
                                String

                                Required

                                A message that describes the current error.
                                __type
                                "urn:inin.com:configuration:configurationError"

                                Required

                                The JSON type representing this option.
                                errorId
                                String
                                The error identifier that describes the current error.
                                message
                                String

                                Required

                                A message that describes the current error.
                                unknownValidator
                                0
                                Unknown validator.
                                uniqueInstanceId
                                1
                                The value must be unique across objects of this type.
                                existingInstanceId
                                2
                                The value must represent a valid ID for a configured instance.
                                existingAttributeValue
                                3
                                The value must match a configured instance.
                                requiredValue
                                4
                                The value must be specified.
                                range
                                5
                                The value must be in the correct range.
                                stringLength
                                6
                                The value must have the correct number of characters.
                                regex
                                7
                                The value must be formatted correctly.
                                validValues
                                9
                                The value is not from the allowed set.
                                collectionCount
                                10
                                The value must have the correct number of items.
                                collectionItemValidator
                                11
                                One or more items failed to validate successfully.
                                validatorGroup
                                12
                                The value is not from the allowed set.
                                validFormat
                                13
                                The value is not in a valid format.
                                uniqueAttributeValue
                                14
                                The value must be unique across attributes of this type.
                                requiredAttribute
                                15
                                The attribute must be specified.
                                acgTreeValidator
                                16
                                The Acg Tree either could not be verified or found, or the Acg Tree depth is not supported.
                                pronunciationValidator
                                17
                                The value is not a valid pronunciation format.
                                wordValidator
                                18
                                The value must be a valid word.
                                rangeFloat
                                19
                                The value must be in the correct range.
                                existingAttendantProfile
                                20
                                The value must match a configured attendant profile instance.
                                extension
                                21
                                The value must not be an existing extension.
                                workstationsSharedAppearanceID
                                22
                                Unknown validator.
                                multipleOf
                                23
                                The value is not a valid multiple value.
                                invalidCharacters
                                24
                                The value contains invalid characters.
                                existingExtension
                                25
                                The value must be an existing extension.
                                existingInstanceIdWithAttributeValue
                                26
                                The value must represent a valid ID for a configured instance.
                                characterDelimitedValue
                                27
                                The value contains invalid characters.
                                analyzerKeywordCount
                                28
                                The number of keywords assigned to the keyword set makes the configuration exceed the maximum number of supported keywords.
                                workgroupAnalyzerKeywordCount
                                29
                                The number of keywords assigned to the workgroup is greater than the maximum number of supported keywords.
                                endDateTimeValidator
                                30
                                The end date or time of a schedule must be greater than or equal to the start date or time.
                                propertyNotApplicable
                                31
                                This property is not applicable with the current configuration.
                                invalidMailboxFolder
                                32
                                The value is not a valid mailbox.
                                unsupportedManufacturer
                                33
                                The provided phone manufacturer is unsupported.
                                unsupportedModel
                                34
                                The provided phone model is unsupported.
                                audioProtocol
                                35
                                An Audio protocol value of SRTP is only supported when the Registration Group for the configuration object has one or more registered lines with a Transport Protocol of TLS.
                                recorderPolicyAnalyzerKeywordCount
                                36
                                The number of keywords assigned to the keyword set makes at least one Recorder Policy exceed the maximum number of supported keywords.
                                referenceCount
                                37
                                The number of reference to this object is exceeding the maximum limit.
                                Feature Version
                                configuration 8
                                wrapUpStatusTimeout
                                38
                                The values of WrapUpStatus or WrapUpTimeout are not valid.
                                Feature Version
                                configuration 8
                                attributeExistence
                                39
                                One or more required attributes was not specified and/or one or more required absent attributes was specifed.
                                Feature Version
                                configuration 8
                                otherAttributeValue
                                40
                                The otherAttributeValue property is expected to have (or not have) a value.
                                Feature Version
                                configuration 8
                                networkAdapter
                                41
                                The network adapter is invalid.
                                Feature Version
                                configuration 8
                                integerComparisonValidator
                                42
                                The integer comparison failed validation based on the comparison type selected.
                                Feature Version
                                configuration 8
                                timeZoneValidator
                                43
                                The time zone is invalid.
                                Feature Version
                                configuration 8
                                existingLanguageValues
                                44
                                The values provided must be languages supported by PureConnect.
                                Feature Version
                                configuration 8
                                characterDelimitedKVPairs
                                45
                                The character delimited key-value pairs are invalid.
                                Feature Version
                                configuration 8
                                objectValidationErrorMutuallyExclusive
                                46
                                Two configuration values are mutually exclusive.
                                Feature Version
                                configuration 10
                                propertyName
                                String

                                Required

                                propertyValue
                                String

                                Required

                                setOK
                                0
                                Setting the license succeeded. This value is never sent.
                                setWarningExceedsThreshold
                                1
                                Indicates that a dynamic license was found with an assignment count that exceeds it's assignable and or concurrent thresholds. As this is only a warning to indicate problems, the license in the request was set successfully.
                                setErrorExceedsThreshold
                                2
                                Indicates that a dynamic license being set exceed it's assignable or concurrent thresholds and was not set as a result. This can be returned for any license assigned to a user or station as part of setting it's licenses because they are all checked for problems as part of the operation.
                                setWarningMissingQualifiers
                                3
                                Indicates that the ACD media level in the request did not have a corresponding set of ACD media types and the default value(s) for the level were set as a result.
                                403 - Forbidden
                                Not authorized to create this resource.
                                error
                                Provides additional detail for an error.
                                Property
                                Value
                                Comments
                                errorId
                                String
                                The error identifier that describes the current error.
                                message
                                String

                                Required

                                A message that describes the current error.
                                500 - Internal Server Error
                                An unexpected error occurred while processing the request.

                                Error Responses

                                Error Identifier
                                Error Type
                                Error Description
                                error.request.internalServerError
                                Type: urn:inin.com:common:error
                                The server encountered an unexpected, internal error.
                                Feature Version
                                configuration 2
                                error.request.timeout
                                Type: urn:inin.com:common:error
                                The request timed out.
                                Feature Version
                                configuration 2
                                error
                                Provides additional detail for an error.
                                Property
                                Value
                                Comments
                                errorId
                                String
                                The error identifier that describes the current error.
                                message
                                String

                                Required

                                A message that describes the current error.
                                401 - Unauthorized
                                The specified session token is missing, invalid, or has expired.
                                Parameters
                                Type
                                Name
                                Comments
                                Header
                                WWW-Authenticate

                                Required

                                Indicates that the client needs to authenticate using a custom ICWS scheme, which supports a realm of type ICWS and a location which is the URL at which the client can authenticate. A typical example would be the following.

                                WWW-Authenticate: ICWS realm="ICWS" location="/ICWS/connection"

                                  error
                                  Provides additional detail for an error.
                                  Property
                                  Value
                                  Comments
                                  errorId
                                  String
                                  The error identifier that describes the current error.
                                  message
                                  String

                                  Required

                                  A message that describes the current error.
                                  410 - Gone
                                  This resource has been deprecated and removed from the API.
                                  error
                                  Provides additional detail for an error.
                                  Property
                                  Value
                                  Comments
                                  errorId
                                  String
                                  The error identifier that describes the current error.
                                  message
                                  String

                                  Required

                                  A message that describes the current error.