exportLevels
Diese API unterstützt nur Benutzer Konzept: Zugriffsregeln in API v22 und höher.
Kategorie
| Abrufen von Metadaten |
Beschreibung
| Gibt Metadaten für die vollständige Liste aller Organisationsebenen im System zurück. |
Zum Aufrufen sind Berechtigungen erforderlich
| Keine (es müssen gültige Zugangsdaten für die Instanz sein) |
Auf Anforderung erforderliche Parameter
| Zugangsdaten |
Die Anforderung dieser Methode enthält ein Tag mit Zugangsdaten, um den aufrufenden Benutzer zu identifizieren und zu autorisieren, sowie ein optionales Tag include, das angibt, welche Ebenen in die Antwort aufgenommen werden sollen. Nachdem die Benutzerzugangsdaten verifiziert wurden, gibt die Methode ein XML-Dokument zurück, das die Organisationsebenen im System beschreibt, die der Anforderung entsprechen. Ebenen werden in einer verschachtelten Baumform zurückgegeben, wobei ein Ebenen-Tag ein anderes einschließt, wenn die durch das umschließende Tag dargestellte Ebene die übergeordnete Ebene der eingeschlossenen Ebene ist.
Filtern nach Ebene
- Der Filter „Ebene/Version nicht verfügbar“ wird immer angewendet, wenn eine Version angegeben wird.
- Wenn ein Benutzer in der Anforderung ein Tabellenblatt mit Benutzerzuweisung angibt, gilt Folgendes:
- Ebenen werden zurückgegeben, wenn der Benutzer Zugriff auf dieses Tabellenblatt hat. Für Administratoren, wenninaccessibleValues„true“ ist, werden Ebenen für das Tabellenblatt zurückgegeben.
- Alle Ebenen im Tabellenblatt werden zurückgegeben, wenn der Benutzer Zugriff auf das Tabellenblatt hat, unabhängig vom Ebenenzugriff des Benutzers.
- Wenn ein Benutzer in der Anforderung ein Tabellenblatt mit Ebenenzuweisung angibt, gilt Folgendes:
- Die Filterung für den Benutzerzugriff wird angewendet, wenn dies erforderlich istinaccessibleValues,welche bestimmt, ob die Antwort Ebenen enthalten soll, auf die der Benutzer keinen Zugriff hat.
- Dann wird die Tabellenblattfilterung angewendet.
Anforderungsformat
<?xml version='1.0' encoding='UTF-8'?> <call method="exportLevels" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <include versionID="3" inaccessibleValues="false"/> <sheet id="3" /> </call>
Element „Zugangsdaten“.
| |||
Tag-Name
| -Zugangsdaten | ||
Beschreibung
| Alle API-Aufrufe müssen ein einzelnes Element mit den Zugangsdaten enthalten, um den Benutzer zu identifizieren, der die API aufruft. Der API-Aufruf wird dann als dieser Benutzer ausgeführt (jeder Audit-Trail oder jede Aktionshistorie im System zeigt, dass dieser Benutzer die Aktion ausgeführt hat). Daher muss der Benutzer über die erforderlichen Berechtigungen verfügen, um die Aktion in Reihenfolge für die API auszuführen -Aufruf erfolgreich ist. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
anmelden | J | Der Anmeldename des Benutzers, der die API-Methode aufruft. Dieser Benutzer muss über die erforderlichen Berechtigungen zum Aufrufen der Methode verfügen. | sampleuser@company.com |
Kennwort | J | Das Kennwort des Benutzers, der die API-Methode aufruft. | my_password |
Gebietsschema | N | Geben Sie das Gebietsschema an, das verwendet werden soll, um eingehende Zahlen und Datumsangaben zu interpretieren und ausgehende Zahlen und Datumsangaben zu formatieren (mit dem entsprechenden Tausendertrennzeichen, den Monatsnamen und der Datumsformatierung). Das Gebietsschema wird auch verwendet, um die Sprache anzugeben, in der Systemmeldungen in der Antwort angezeigt werden sollen. Wenn nicht angegeben, wird en_US (amerikanisches Englisch) verwendet. | fr_FR |
instanceCode | N | Wenn der in den Zugangsdaten angegebene Benutzer Zugriff auf mehr als eine Instanz von hat, Adaptive Planning : Dieses Attribut kann verwendet werden, um anzugeben, dass der Benutzer auf eine andere Instanz als seine Standardinstanz zugreifen möchte. Wenn nicht angegeben, wird die Standardinstanz des Benutzers verwendet. Verwenden Sie die exportInstances-API, um die verfügbaren Instanzcodes zu ermitteln. | MYINSTANCE1 |
Inhalt des Elements
| |||
(Keine) | |||
Element einschließen
| |||
Tag-Name
| einschließen | ||
Beschreibung
| Stellt einen Satz von Kennzeichen dar, die angeben, welche Aspekte der Ebeneninformationen in die Antwort aufgenommen oder daraus ausgeschlossen werden sollen. Dieses Element ist optional: Wenn es nicht vorhanden ist, ist der Standardwert "false" für in AccessibleValues und leer (oder alle Versionen) für versionName/versionID. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Gruppe(n) Verfügbar in API v23 und höher. | N | Gibt an, ob die Ebenenelemente in der Antwort ein Attribut groupIds enthalten. Bei wahr enthalten die groupIds in der Antwort eine durch Kommas getrennte Liste aller Gruppen, in denen sich die Ebene befindet. Wenn das Attribut nicht vorhanden ist oder sein Wert nicht „true“ oder „false“ ist, wird der Standardwert „false“ verwendet. | wahr |
in AccessibleValues Verfügbar in API v18 und höher. | N | Ob die Antwort Ebenen enthalten soll, auf die der Benutzer keinen Zugriff hat. Entweder wahr oder falsch. Wenn das Element oder sein Attribut nicht vorhanden ist, ist der Standardwert „false“. Bei „false“ enthält die Antwort nur Ebenen, auf die der Benutzer direkt oder implizit Datenzugriff hat. Beachten Sie, dass dies bedeutet, dass die Antwort möglicherweise nicht mehr ein einzelner Root-Baum von Ebenen ist, sondern eine Reihe von getrennten Unterbäumen des übergeordneten Baums. Nur Benutzer mit den Berechtigungen "Organisationsstruktur: alle Ebenen" oder "In alle Ebenen importieren" können diese Option auf "true" setzen. | false |
in AccessibleLevels Verfügbar in API v17 und früher. Nicht verfügbar in API v18 und höher. | N | Entweder wahr oder falsch. Ob die Antwort Ebenen enthalten soll, auf die der Benutzer keinen Zugriff hat. Der Standardwert, wenn das Element oder sein Attribut nicht vorhanden ist, ist „true“. Bei „false“ enthält die Antwort nur Ebenen, auf die der Benutzer direkt oder implizit Datenzugriff hat. Beachten Sie, dass dies bedeutet, dass die Antwort möglicherweise nicht mehr ein einzelner Root-Baum von Ebenen ist, sondern eine Reihe von getrennten Unterbäumen des übergeordneten Baums. | wahr |
versionName Aktualisiert in API v18 | N | Gibt an, ob die Antwort nur Ebenen enthalten soll, die für den angeforderten Versionsnamen verfügbar sind. Wenn das Element oder sein Attribut nicht vorhanden ist, werden standardmäßig alle Ebenen zurückgegeben. Wenn ein Versionsname angegeben wird, werden nur Ebenen zurückgegeben, die für die angegebene Version verfügbar sind. Falls vorhanden, wird auch das Attribut in AccessibleValues angewendet und es werden nur Ebenen zurückgegeben, die in der angegebenen Version verfügbar sind und auf die der anfordernde Benutzer zugreifen kann. Wenn der angegebene Versionsname nicht gefunden wird, gibt diese API einen Fehler zurück. Wenn sowohl das Attribut versionName als auch versionID übergeben werden, wird die versionID ignoriert. Wenn Sie eine Version angeben, ist der Aufruf nur dann erfolgreich, wenn der Benutzer Zugriff auf die Version hat. | Engineering |
versionID Aktualisiert in API v18 | N | Identisch mit versionName (oben), außer dass eine Versions-ID-Nummer als Parameter verwendet wird. Gibt an, ob die Antwort nur Ebenen enthalten soll, die für die angeforderte Version verfügbar sind. Wenn das Element oder sein Attribut nicht vorhanden ist, werden standardmäßig alle Ebenen zurückgegeben. Wenn eine Versions-ID angegeben wird, werden nur Ebenen zurückgegeben, die für die angegebene Version verfügbar sind. Falls vorhanden, wird auch das Attribut in AccessibleValues angewendet und es werden nur Ebenen zurückgegeben, die in der angegebenen Version verfügbar sind und auf die der anfordernde Benutzer zugreifen kann. Wenn die angegebene Versions-ID nicht gefunden wird, gibt diese API einen Fehler zurück. Wenn sowohl das Attribut versionName als auch versionID übergeben werden, wird die versionID ignoriert. Wenn Sie eine Version angeben, ist der Aufruf nur dann erfolgreich, wenn der Benutzer Zugriff auf die Version hat. | 3 |
Ohne Kategorie Wird in API v22 und höher unterstützt, wenn die Instanz aus Sicherheitsgründen Zugriffsregeln verwendet. | N | Gibt an, ob die Pseudoebenen in die Antwort aufgenommen werden sollen. Der Standardwert ist „false“. Die Ebenen werden nur dann in die Antwort aufgenommen, wenn der Benutzer Zugriff auf sie hat. | false |
displayNameEnabled
Nur in API v30 und höher für Instanzen verfügbar, die den Anzeigenamen aktivieren. | N | displayNameEnabled=true gibt an, dass exportLevels die Eigenschaften des Anzeigenamens von berücksichtigen sollten code , displayNameType , und description wenn Enable Anzeige Name für die Instanz EIN ist.displayNameEnabled=false gibt an, dass die exportLevels API weiterhin den API-Vertrag vor v30 einhalten soll, auch wenn "Anzeigenamen aktivieren" für die Instanz auf EIN gesetzt ist. Die exportLevels-API ignoriert die Eigenschaften des Anzeigenamens code , displayNameType und description .Der Standardwert für displayNameEnabled ist "false". | false |
Inhalt des Elements
| |||
(Keine) | |||
Tabellenblattelement
| |||
Tag-Name
| Tabellenblatt | ||
Beschreibung
| Stellt ein Tabellenblatt dar, in dem nur die für dieses Tabellenblatt verfügbaren Ebenen in die Antwort aufgenommen werden. Dieses Element ist optional: Wenn es nicht vorhanden ist, gibt die API Ebeneninformationen unabhängig von einem bestimmten Tabellenblatt zurück. Wenn es sich bei dem angegebenen Tabellenblatt um ein Tabellenblatt mit Ebenenzuweisung handelt, wird diese Filterung zusätzlich zur Version und zum Benutzerzugriff angewendet, falls vorhanden. Wenn es sich bei dem angegebenen Tabellenblatt um ein Tabellenblatt mit Benutzerzuweisung handelt, auf das der aktuelle Benutzer Zugriff hat, werden alle Ebenen in diesem Tabellenblatt nach jeder Versionsfilterung zurückgegeben. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
id | J | Die interne System-ID-Nummer für das Tabellenblatt. | 234 |
Inhalt des Elements
| |||
(Keine) | |||
Antwortformat
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <output> <levels seqNo="21"> <level id="1" name="Corporate Rollup" currency="USD" isImportable="1" workflowStatus="I"> <level id="2" name="Engineering" currency="USD" shortName="Engr" isImportable="1" workflowStatus="I"> <level id="7" name="Development" currency="USD" shortName="Dev" isImportable="1" workflowStatus="I"/> <level id="8" name="QA" currency="INR" isImportable="0" workflowStatus="L"/> <level id="9" name="Documentation" currency="PKR" shortName="Doc" isImportable="1" workflowStatus=R"/> </level> <level id="3" name="Professional Services" currency="USD" shortName="Prof.Srv" isImportable="0" workflowStatus="A"> <attributes> <attribute name="Corporate Discount" value="Available" attributeId="20" valueId="188" /> <attribute name="Transfers Restricted" value="Yes" attributeId="21" valueId="194" /> </attributes> </level> </level> </levels> </output> </response>
Antwortelement
| |||
Tag-Name
| -Antwort | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Erfolg haben | J | Entweder wahr oder falsch, was angibt, ob der API-Aufruf erfolgreich war oder nicht. Selbst erfolgreiche Aufrufe können in ihrer Antwort Warnmeldungen enthalten. | wahr |
veraltet | N | Wenn dieses Attribut im Antwort-Tag vorhanden ist und auf „true“ gesetzt ist, zeigt es an, dass die Version der Methode oder API, die aufgerufen wird, veraltet und offiziell veraltet ist. Auch wenn es zu diesem Zeitpunkt noch funktioniert, kann es sein, dass Sie in Kürze nicht mehr funktionieren. In der Regel ist dieses Attribut nicht vorhanden. | false |
Inhalt des Elements
| |||
Ein einzelnes optionales Nachrichtenelement und genau ein erforderliches Ausgabeelement. | |||
Ausgabeelement
| |
Tag-Name
| Ausgabe |
Attribute des Elements
| |
(Keine) | |
Inhalt des Elements
| |
Ein einzelnes Kontenelement Dieser Ausgabe-Wraper ist ein Standard für alle API-Antworten und schließt die gültige Ausgabe jedes erfolgreichen API-Aufrufs ein. | |
Element „Ebenen“.
| |||
Tag-Name
| Ebene(n) | ||
Beschreibung
| Container für das Element Ebenen. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Sequenznr Hinzugefügt in API v17, aber für zukünftige Verwendung reserviert. | |||
Inhalt des Elements
| |||
Ein oder mehrere Ebenenelemente. Wenn die Anforderung unzugängliche Ebenen enthält, gibt es nur ein Ebenenelement, das die oberste Ebene der Organisation darstellt. | |||
Ebenenelement
| |||
Tag-Name
| level | ||
Beschreibung
| Stellt eine einzelne Organisationsebene dar, die in der Antwort auf einen API-Aufruf exportLevels zurückgegeben wird. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
id | J | Die interne System-ID der Ebene. | 7 |
-Code
Nur in API v30 und höher für Instanzen verfügbar, die den Anzeigenamen aktivieren. | N | Der Code der Ebene. | Entwicklung |
Name | J | Der Name der Ebene, wie er in Berichten und Tabellenblättern angezeigt wird. | Entwicklung |
displayName
Nur in API v30 und höher für Instanzen verfügbar, die den Anzeigenamen aktivieren. | N | Der Anzeigename der Ebene, wie aus displayNameType abgeleitet. | Entwicklung |
Währung | J | Der Währungscode für die Währung, die dieser Ebene der Organisation zugewiesen ist. Die Währung ist eine der konfigurierten Währungen für die Instanz, die im Aufruf exportActiveCurrencies gefunden wurde. | INR |
publishCurrency Verfügbar in API v24 und höher | N | Der Währungscode für die Währung, die der Veröffentlichung ab dieser Ebene zugewiesen ist. Diese Eigenschaft ist nur anwendbar, wenn „Power of One“ für die Instanz aktiviert wurde. Die Währung ist eine der konfigurierten Währungen für die Instanz, die im Aufruf exportActiveCurrencies gefunden wurde. | USD |
shortName | N | Die Abkürzung für die Ebene, falls vorhanden, wie in der Ebenenverwaltung eingegeben. | Abw |
availableStart | N | Die Startzeitperiode für die Verfügbarkeit der Ebene für die Istzahlen-Version. Sie gilt nur, wenn in der Anforderung die IST-Version angegeben wird. Der Wert kann entweder ein Zeitperiodencode sein, z. B. „01/2012“, oder der Sonderwert „START“, der den Versionsstart angibt. | 01/2013 |
availableEnd | N | Die Endzeitperiode für die Verfügbarkeit der Ebene für die Istzahlen-Version. Sie gilt nur, wenn in der Anforderung die IST-Version angegeben wird. Der Wert kann entweder ein Zeitperiodencode sein, z. B. „12/2013“, oder der Sonderwert „END“, der das Versionsende angibt. | 12/2013 |
isImportable | N | Gibt an, ob die zugeordnete Ebene in der angegebenen Version importierbar ist. "0" bedeutet, dass sie nicht importierbar ist und "1" bedeutet, dass sie importierbar ist. Eine Ebene ist importierbar, wenn mindestens ein Zeitfenster in der angegebenen Version importierbar ist. Das Attribut isImportable wird nur ausgegeben, wenn in der Anforderung versionName oder versionID angegeben ist. Hinweis: isImportable gibt nur an, dass eine Ebene für den Import in der angegebenen Version verfügbar ist, und nicht, dass der Benutzer, der den API-Aufruf ausführt, die Berechtigung zum Importieren in die Version oder Ebene hat. Verwenden Sie exportVersions, um anzuzeigen, welche Versionen dem Benutzer für den Import zur Verfügung stehen. | 1 |
workflowStatus | N | Gibt den Workflow-Status für die zugeordnete Ebene aus. I für „In Bearbeitung“, S für „Übermittelt“, R für „Abgelehnt“, A für „Genehmigt“ und L für „Gesperrt“. Wird nur in die Antwort aufgenommen, wenn Workflow für dieses Unternehmen aktiviert ist und in der Anforderung eine PlanversionName oder eine Versions-ID angegeben ist. Workflow ist für Istzahlen-Versionen nicht verfügbar. | I |
isLinked | J | 1, wenn die Ebene eine verknüpfte Ebene ist; andernfalls 0. | 1 |
isElimination | J | 1, wenn die Ebene eine Eliminierungsebene ist; andernfalls 0. | 0 |
hasChildren | N | Gibt an, ob die Ebene untergeordnete Ebenen hat. „false“ für „nein“, „true“ für „ja“. Dieses Attribut wird für jede Ebene mit untergeordneten Ebenen festgelegt, unabhängig davon, ob auf die untergeordneten Ebenen zugegriffen werden kann oder nicht. Wenn eine Ebene untergeordnete Ebenen hat, auf die untergeordneten Ebenen jedoch nicht zugegriffen werden kann, wird das Attribut hasChildren dennoch auf „true“ gesetzt. | wahr |
Beschreibung
Nur in API v30 und höher für Instanzen verfügbar, die den Anzeigenamen aktivieren. | N | Die Beschreibung der Ebene, falls vorhanden, wie sie in der Ebenenverwaltung eingegeben wurde. | |
Inhalt des Elements
| |||
Ein verschachteltes Ebenenelement für jede direkt untergeordnete Ebene dieser Ebene. Ein Attributelement, wenn dieser Ebene mindestens ein Attribut zugeordnet ist. | |||
Element „Attribute“.
| |||
Tag-Name
| Attribute | ||
Beschreibung
| Container für ein oder mehrere Attributelemente. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
(Keine) | |||
Inhalt des Elements
| |||
Ein oder mehrere Attributelemente. | |||
Attributelement
| |||
Tag-Name
| Attribut | ||
Beschreibung
| Stellt ein einzelnes Attribut-Mapping für nicht leere Ebenen dar, dem eine Ebene zugeordnet ist. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Name | J | Der Name des Ebenenattributs | Unternehmensrabatt |
Wert
Wird in API v34 unterstützt, wenn die Einstellung Gültiger Anzeigename auf EIN gesetzt ist. | J | Der Wert des Ebenenattributs, das der Ebene zugeordnet ist. | Ja |
valueCode
Nur in API v32 und API v33 für Instanzen verfügbar, die den Anzeigenamen aktivieren. Wird in API v34 nicht unterstützt, wenn die Einstellung "Gültiger Anzeigename" auf EIN gesetzt ist. | N | Der Code des Attributwerts für dieses Attribut.
Für API v32 und v33 ist valueCode nur in folgenden Fällen sinnvoll:
| J |
valueName
Nur in API v32 und API v33 für Instanzen verfügbar, die den Anzeigenamen aktivieren. Wird in API v34 nicht unterstützt, wenn die Einstellung "Gültiger Anzeigename" auf EIN gesetzt ist. | N | Der Name des Attributwerts für dieses Attribut.
Für API v32 und API v33 ist valueName nur in folgenden Fällen sinnvoll:
| Ja |
valueDisplayName
Nur in API v32 und höher für Instanzen verfügbar, die den Anzeigenamen aktivieren. | J | Der Anzeigename des Attributwerts.
Für API v32 und höher ist valueDisplayName nur in folgenden Fällen sinnvoll:
| Ja |
attributeID | J | Die interne System-ID-Nummer des Ebenenattributs. | 20 |
valueID | J | Die interne System-ID des Ebenenattributwerts. | 188 |
Inhalt des Elements
| |||
(Keine) | |||