Authentication
Following authentication types are supported:
-
basic (/ufmRest)
-
client (/ufmRestV2)
-
token (/ufmRestV3)
General
-
Description – allow users to query the fabric to identify GUIDs assignments to PKeys using the Actions/Jobs REST API
-
Request URL
/ufmRestV2/actions/pkeys -
Actions
-
Report a specific PKey or list of PKeys
-
Report all PKeys
-
Verify a specific PKey or list of PKeys
-
Verify all PKeys
-
Check Set GUIDs to PKey – monitor completion of a Set operation
-
Check Add GUIDs to PKey – monitor completion of an Add operation
-
Check Del GUIDs from PKey – monitor completion of a Delete operation
-
-
Note: All actions are performed asynchronously and require polling to provide the response when completed
-
Response to actions when started
<!doctype html> <html lang=en> <title>Redirecting...</title> <h1>Redirecting...</h1> <p>You should be redirected automatically to the target URL: <a href="/ufmRestV2/jobs/JOBID">/ufmRestV2/jobs/JOBID</a>. If not, click the link.
Jobs REST API responses
-
Description - use the jobs REST API to obtain results for actions
-
Request URL –
GET /ufmRestV2/jobs/<JOBID> -
Status codes
-
200 - OK
-
404 - Not Found
-
{
"ID": "<JOBID>",
"Status": "<STATUS>",
"Progress": <PERCENT>,
"Description": "PKeys monitoring: <ACTION> (<PKEY-DESC>)",
"Created": "<time-stamp-1>",
"LastUpdated": "<time-stamp-2>",
"Summary": <RESULT>,
"RelatedObjects": <INPUT>,
"CreatedBy": "admin",
"Operation": "pkeys",
"Foreground": true,
"SiteName": ""
}
-
<INPUT> is the JSON of the action request.
-
<ACTION> is the action name (REPORT / VERIFY / CHKADD / CHKSET / CHKDEL).
-
<PKEY-DESC> is either “PKey 0x<pkey>”, “Multiple PKeys” or “All PKeys”.
-
While Action is pending, <STATUS> is “Running”, <PERCENT> is 0 and <RESULT> is “”.
-
When Action response is ready, <STATUS> is either “Completed” or “Completed With Errors”, <PERCENT> is 100 and <RESULT> is the JSON of the result from RAMP.
NOTE: The “id” within the result JSON is an internal id used by RAMP and has no relation to the <JOBID> used to obtain action results.
Completion Status
A completed PKeys monitoring action will be reported by the job <STATUS> as completed if the result internal status is “completed” and the only GUID list shown is under “guids”.
Otherwise - the job <STATUS> will be “Completed With Errors”.
Report a Specific PKey (or List of PKeys)
-
Description – query the fabric to show which GUIDs have a specific PKey
-
Request URL –
POST /ufmRestV2/actions/pkeys -
Request content type – Application/json
-
Action request parameter value – "REPORT"
-
Other request parameters
|
Name |
Value |
Default |
Description |
Mandatory/ Optional |
|---|---|---|---|---|
|
action |
"REPORT" |
None |
Name of action |
Mandatory |
|
entries |
An array of objects. Each object has a "pkey" field |
None |
Each entry provides information about a PKey to report about |
Mandatory, at least one entry |
|
entries.pkey |
Hexadecimal string between "0x0"-"0x7fff" exclusive |
None |
Network PKey |
Mandatory |
|
timeout |
An integer between 1 and 200 |
30 |
Number of seconds to wait for the action to complete |
Optional |
-
Status Codes
-
202 – Accepted
-
400 – Bad Request
-
-
Response – "location" header contains query URL
-
Location: /ufmRestV2/jobs/<JOBID>
-
-
Request Data Example
{ "action": "REPORT", "entries": [ { "pkey": "0x1234" } ] }
-
Result – example of final response to query
{ "id": 11, "action": "REPORT", "status": "completed", "result": [ { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] } ] }
Report all PKeys
-
Description – query the fabric to show all PKeys and the GUIDs associated with them
-
Request URL –
POST /ufmRestV2/actions/pkeys -
Request content type – Application/json
-
Action request parameter value – "REPORT"
-
Other request parameters
|
Name |
Value |
Default |
Description |
Mandatory/ Optional |
|---|---|---|---|---|
|
action |
"REPORT" |
None |
Name of action |
Mandatory |
|
all |
true |
None |
All PKeys should be reported |
Mandatory |
|
timeout |
An integer between 1 and 200 |
30 |
Number of seconds to wait for the action to complete |
Optional |
-
Status Codes
-
202 – Accepted
-
400 – Bad Request
-
-
Response – "location" header contains query URL
-
Location: /ufmRestV2/jobs/<JOBID>
-
-
Request Data Example
{ "action": "REPORT", "all": true }
-
Result – example of final response to query
{ "id": 12, "action": "REPORT", "status": "completed", "result": [ { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] }, { "pkey": "0x5678", "guids": [ "b8cef6030083b777", "946dae03002ac111" ] } ] }
Verify a Specific PKey (or list of PKeys)
-
Description – query the fabric to show which of the GUIDs requested to have a specific PKey were configured accordingly
-
Request URL –
POST /ufmRestV2/actions/pkeys -
Request content type – Application/json
-
Action request parameter value – "VERIFY"
-
Other request parameters
|
Name |
Value |
Default |
Description |
Mandatory/ Optional |
|---|---|---|---|---|
|
action |
"VERIFY" |
None |
Name of action |
Mandatory |
|
entries |
An array of objects. Each object must have a "pkey" field |
None |
Each entry provides information about a PKey to report about |
Mandatory, at least one entry |
|
entries.pkey |
Hexadecimal string between "0x0"-"0x7fff" exclusive |
None |
Network PKey |
Mandatory |
|
entries.guids |
["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters |
[] |
A list of GUIDs presumed to be associated with the PKey. If not provided or empty, UFM will be queried to provide the list |
Optional |
|
timeout |
An integer between 1 and 200 |
30 |
Number of seconds to wait for the action to complete |
Optional |
-
Status Codes
-
202 – Accepted
-
400 – Bad Request
-
-
Response – "location" header contains query URL
-
Location: /ufmRestV2/jobs/<JOBID>
-
-
Request Data Example
{ "action": "VERIFY", "entries": [ { "pkey": "0x1234" } ] }
-
Result – example of final response to query
{ "id": 13, "action": "VERIFY", "status": "completed", "result": [ { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ], "missing": [], "wrong": [] } ] }
Verify all PKeys
-
Description – query the fabric to show for all PKeys which of the GUIDs associated with each PKey have actually been configured
-
Request URL –
POST /ufmRestV2/actions/pkeys -
Request content type – Application/json
-
Action request parameter value – "VERIFY"
-
Other request parameters
|
Name |
Value |
Default |
Description |
Mandatory/ Optional |
|---|---|---|---|---|
|
action |
"VERIFY" |
None |
Name of action |
Mandatory |
|
all |
true |
None |
All PKeys should be verified. UFM will be queried to provide the list (PKeys and GUIDs) |
Mandatory |
|
timeout |
An integer between 1 and 200 |
30 |
Number of seconds to wait for the action to complete |
Optional |
-
Status Codes
-
202 – Accepted
-
400 – Bad Request
-
-
Response – "location" header contains query URL
-
Location: /ufmRestV2/jobs/<JOBID>
-
-
Request Data Example
{ "action": "VERIFY", "all": true }
-
Result – example of final response to query
{ "id": 14, "action": "VERIFY", "status": "completed", "result": [ { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ], "missing": [], "wrong": [] }, { "pkey": "0x5678", "guids": [ "b8cef6030083b777", "946dae03002ac111" ], "missing": [], "wrong": [] } ] }
Monitor Setting of GUIDs to a PKey
-
Description – Monitor the setting of a group of GUIDs to a PKey
-
Request URL –
POST /ufmRestV2/actions/pkeys -
Request content type – Application/json
-
Action request parameter value – "CHKSET"
-
Other request parameters
|
Name |
Value |
Default |
Description |
Mandatory/ Optional |
|---|---|---|---|---|
|
action |
"CHKSET" |
None |
Name of action |
Mandatory |
|
entry |
An object with a "pkey" field and a "guids" field |
None |
Each entry provides information about a PKey to report about |
Mandatory |
|
entry.pkey |
Hexadecimal string between "0x0"-"0x7fff" exclusive |
None |
Network PKey |
Mandatory |
|
entry.guids |
["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters |
[] |
A list of GUIDs presumed to be associated with the PKey.
|
Mandatory |
|
timeout |
An integer between 1 and 200 |
30 |
Number of seconds to wait for the action to complete |
Optional |
-
Status Codes
-
202 – Accepted
-
400 – Bad Request
-
-
Response – "location" header contains query URL
-
Location: /ufmRestV2/jobs/<JOBID>
-
-
Request Data Example
{ "action": "CHKSET", "entry": { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] }, "timeout": 60 }
-
Result – example of final response to query
{ "id": 15, "action": "CHKSET", "status": "completed", "result": [ { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] } ] }
Monitor Adding GUIDS to a PKey
-
Description – Monitor the assignment of a group of GUIDs to a PKey
-
Request URL –
POST /ufmRestV2/actions/pkeys -
Request content type – Application/json
-
Action request parameter value – "CHKADD"
-
Other request parameters
|
Name |
Value |
Default |
Description |
Mandatory/Optional |
|---|---|---|---|---|
|
action |
"CHKADD" |
None |
Name of action |
Mandatory |
|
entry |
An object with a "pkey" field and a "guids" field |
None |
Each entry provides information about a PKey to report about |
Mandatory |
|
entry.pkey |
Hexadecimal string between "0x0"-"0x7fff" exclusive |
None |
Network PKey |
Mandatory |
|
entry.guids |
["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters |
[] |
A list of GUIDs presumed to be associated with the PKey.
|
Mandatory |
|
timeout |
An integer between 1 and 200 |
30 |
Number of seconds to wait for the action to complete |
Optional |
-
Status Codes
-
202 – Accepted
-
400 – Bad Request
-
-
Response – "location" header contains query URL
-
Location: /ufmRestV2/jobs/<JOBID>
-
-
Request Data Example
{ "action": "CHKADD", "entry": { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] }, "timeout": 60 }
-
Result – example of final response to query
{ "id": 16, "action": "CHKADD", "status": "completed", "result": [ { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] } ] }
Monitor Removing GUIDs from a PKey
-
Description – Monitor the removal of a group of GUIDs from a PKey
-
Request URL –
POST /ufmRestV2/actions/pkeys -
Request content type – Application/json
-
Action request parameter value – "CHKDEL"
-
Other request parameters
|
Name |
Value |
Default |
Description |
Mandatory/Optional |
|---|---|---|---|---|
|
action |
"CHKDEL" |
None |
Name of action |
Mandatory |
|
entry |
An object with a "pkey" field and a "guids" field |
None |
Each entry provides information about a PKey to report about |
Mandatory |
|
entry.pkey |
Hexadecimal string between "0x0"-"0x7fff" exclusive |
None |
Network PKey |
Mandatory |
|
entry.guids |
["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters |
[] |
A list of GUIDs presumed to be associated with the PKey.
|
Mandatory |
|
timeout |
An integer between 1 and 200 |
30 |
Number of seconds to wait for the action to complete |
Optional |
-
Status Codes
-
202 – Accepted
-
400 – Bad Request
-
-
Response – "location" header contains query URL
-
Location: /ufmRestV2/jobs/<JOBID>
-
-
Request Data Example
{ "action": "CHKDEL", "entry": { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] }, "timeout": 60 }
-
Result – example of final response to query
{ "id": 17, "action": "CHKDEL", "status": "completed", "result": [ { "pkey": "0x1234", "guids": [ "b8cef6030083bea2", "946dae03002ac882" ] } ] }
GUID lists in results
-
“guids” - a list of GUIDs that have the PKey (or in the special case of CHKDEL, GUIDs that don’t have the PKey).
-
“missing” - a list of GUIDs that should have the PKey, but unfortunately don’t have it (currently VERIFY only).
-
“wrong” - a list of GUIDs that should not have the PKey, but unfortunately do have it (currently VERIFY only).
-
“unknown” - an optional list of GUIDs that were explicitly specified in the action, but appear not to be part of the fabric.
-
“unreachable” - an optional list of GUIDs that although being part of the fabric, RAMP was unable to receive a reply to its queries.
Last updated: