updateAttributes
Com suporte na API v20 +
Categoria
| Modificação de metadados |
Descrição
| Atualize um conjunto de atributos existentes, seus valores de atributo e suas propriedades. Vários atributos com vários valores de atributo podem ser atualizados em uma chamada. Se for bem-sucedida, a API retorna detalhes dos atributos que foram atualizados/criados. Se a API falha, uma lista abrangente de erros e suas causas é retornada. |
Permissões obrigatórias para invocar
| Modelo |
Parâmetros obrigatórios na solicitação
| Credenciais |
A solicitação desse método contém uma etiqueta de credenciais para identificar e autorizar o usuário que está fazendo a chamada. O usuário deve ter o "Modelo" Conceito: conjuntos de permissões e a permissão necessária para administrar os atributos que estão sendo atualizados.
Prática recomendada: invoque exportAttributes para recuperar o
Adaptive Planning
IDs de atributo necessárias para sua solicitação updateAttributes. Faça o possível para minimizar o tempo entre as chamadas exportAttributes e updateAttributes.HTTP | Descrição |
|---|---|
Method
| Post
|
Content-Type
| text/xml |
Exemplo de curvatura
curl -H "Content-Type: text/xml" -d @C:/temp/updateAttributes.xml -X POST https://api.adaptiveplanning.com/api/v20
conteúdo de updateAttributes.xml
Formato da solicitação
Update a set of existing attributes and their attribute values, and their <?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <attributes proceedWithWarnings="0"> <attribute id="13" name="AP Eligible" type="account" keepSorted="1"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> </attribute> </attributes> </call>
Para cargas grandes, você pode publicar arquivos XML compactados (zipados). Saiba como aqui.
As seguintes condições se aplicam a updateAttributes:
- Os atributos são identificados para atualização por meio de seu número de ID interno.
- Para criar novos atributos, forneça a eles uma propriedade de ID em branco ou ausente.
- Você pode mover um item existente (não novo) para que ele se torne filho de um novo item. Isso cria o novo item e move o item existente abaixo dele como um filho.
Formato de solicitação para criação de um novo atributo
Para criar um novo atributo,
AP Eligible
, deixe a ID em branco e forneça seu nome e tipo.<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="" name="AP Eligible" type="account"> <attributeValue id="" name="No" /> <attributeValue id="" name="Yes"> <attributeValue id="" name="Full" /> <attributeValue id="" name="Partial" /> </attributeValue> </attribute> </attributes> </call>
Solicitação para criar um novo atributo para uma dimensão de lista
Para criar um novo atributo
Education Type
para uma dimensão de lista, Education.
Os valores de atributo Technical
e seu filho, Tech1,
têm IDs em branco, indicando que são novos.
<?xml version="1.0" encoding="UTF-8"?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password" /> <attributes> <attribute id="" name="Education Type" type="dimension" listDimensionName="Education" keepSorted="1" importAutoCreateValues="1"> <attributeValue id="" name="Technical" description=""> <attributeValue id="" name="Tech1" description="" /> </attributeValue> <attributeValue id="" name="Management" description="" /> </attribute> </attributes> </call>
Formato de solicitação para criação de um novo valor de atributo
future
abaixo de AP Eligible
atributo com id 13
e valor de atributo no
com id 118
, você pode usar:<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="13"> <attributeValue id="118" > <attributeValue id="" name="future" /> </attributeValue> </attribute> </attributes> </call> To create a new attribute value, include its parent by its ID. For example, to add a new attribute value
Este método não altera nada no atributo
id 13
. Cria um novo valor de atributo future
para atributo id 13
e torna seu pai o valor de atributo no
. Todos os valores de atributo não mencionados de no
vá para o fim da lista de valores. Isso equivale a "definir o pai" para o novo valor de atributo.Tratamento de várias renomeações em uma única chamada updateAttributes
Várias renomeações da mesma entidade podem ocorrer em um sistema remoto entre
updateAttributes
chamadas. Os nomes de entidades no sistema remoto podem ser trocados pelas mesmas IDs de entidade. Quando updateAttributes
chamadas ocorrem após a troca de nomes, o updateAttributes
O call gerencia essas alterações rastreando as IDs nas alterações de nome. A chamada também pode lidar com a introdução de uma nova ID que usa um nome existente.Para que cada um dos exemplos seja bem-sucedido, a troca completa de IDs deve ocorrer com os valores exclusivos.
Exemplo 1: uma simples troca de nome no sistema remoto.
To create a new attribute value, include its parent by its ID. For example, to add a new ID Unique Value New Unique Value 1 AA BB 2 BB AA
Exemplo 2: uma sequência de três renomeações no sistema remoto.
ID Unique Value New Unique Value 1 AA BB 2 BB CC 3 CC AA
Exemplo 3: uma nova entidade que usa um valor exclusivo existente.
ID Unique Value New Unique Value 4 AA 1 AA BB 2 BB Old BB
elemento de credenciais
| |||
Nome da etiqueta
| credenciais | ||
Descrição
| Todas as chamadas de API devem conter um único elemento de credenciais para identificar o usuário que invoca a API. A chamada à API é então executada como este usuário (qualquer trilha de auditoria ou histórico de ações no sistema mostrará que este usuário executou a ação) e, portanto, o usuário deve ter as permissões necessárias para executar a ação para que a chamada à API funcione. bem-sucedido. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
login | S | O nome de logon do usuário que invoca o método de API. Esse usuário deve ter as permissões necessárias para invocar o método. | sampleuser@company.com |
senha | S | A senha do usuário que invoca o método de API. | my_password |
parâmetros regionais | N | Especifique os parâmetros regionais a serem usados para interpretar números e datas de entrada e para formatar números e datas de saída (usando o separador de milhares, nomes de meses e formatação de data adequados). Os parâmetros regionais também são usados para especificar o idioma em que as mensagens do sistema na resposta devem ser exibidas. Se não especificado, en_US (inglês americano) é usado. | fr_FR |
instanceCode | N | Se o usuário especificado nas credenciais tem acesso a mais de uma instância do Adaptive Planning , esse atributo pode ser usado para especificar que o usuário pretende acessar uma instância diferente da instância por padrão. Se não for especificada, a instância por padrão do usuário será usada. Para determinar os códigos de instância disponíveis, use a API exportInstances. | MYINSTANCE1 |
Conteúdo do elemento
| |||
(nenhum) | |||
elemento de atributos
| |||
Nome da etiqueta
| atributos | ||
Descrição
| Somente uma solicitação de elemento de atributos é permitida por carga. Ele contém um ou mais elementos de atributo. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
proceedWithWarnings | N | Aplica-se somente à redefinição como pai de valores de atributo. Se houver avisos e continueWithWarnings=0, o attributeValue não será atualizado. Defina prosseguiWithWarnings = 1 para atualizar o attributeValue quando há avisos. Aplica-se somente a type=account e type=level. ProceedWithWarnings=1 (a) a redefinição de parentesco é executada mesmo quando a marcação de atributos de conta/nível se torna incompatível. (b) Todas as etiquetas incompatíveis de atributos de conta/nível serão corrigidas usando a etiqueta de atributo do nível pai. ProceedWithWarnings=0 erros se a redefinição de parentesco com o valor de atributo resultasse na incompatibilidade do mapeamento de atributos de conta/nível. | 1 |
retainExistingOrder Disponível na API v27+ | N | MaintainExistingOrder="1" indica que a updateAttributes API deve ignorar a ordem dos elementos na carga XML e a ordem definida existente será mantida. retExistingOrder="0" indica que a updateAttributes API deve atualizar a ordem dos elementos com base na posição da etiqueta em relação a outros irmãos na carga XML. O indicador MaintainExistingOrder é ignorado quando o atributo tem o indicador "KeepSorted" habilitado. O valor por padrão para reterExistingOrder é "1". | 1 |
DisplayNameEnabled
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | displayNameEnabled = 1 indica que updateAttribues deve respeitar as propriedades de nome de exibição de code , displayNameType e description quando Habilitar nome de exibição está ATIVADO para a instância.displayNameEnabled=0 indica que a updateAttributes API deve continuar seguindo o contrato de API anterior à v30, mesmo quando a opção Habilitar nome de exibição está ATIVADA para a instância. A updateAttributes API ignora as propriedades de nome de exibição code , displayNameType e description .O valor por padrão para displayNameEnabled é "0". | 1 |
Conteúdo do elemento
| |||
Contém um ou mais elementos de atributo. | |||
elemento atributo
| |||
Nome da etiqueta
| atributo | ||
Descrição
| Especifica um atributo a ser criado ou atualizado. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
ID | S | O número da ID do sistema interno para o atributo. | 16 |
nome
Atualizado na API v30 | S | O nome do atributo, como aparece em relatórios e planilhas.
| Ativos atuais |
código
Disponível na API v39+. | N | O código do atributo | Ativos atuais |
displayNameType
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | Controla a exibição de valores de atributo. Os valores possíveis são NAME, CODE, NAME_CODE ou CODE_NAME.
O valor por padrão é NOME quando deixado em branco ou não fornecido. Essa propriedade só fica disponível quando a opção Habilitar nome de exibição está ATIVADA para a instância. | "CODE_NAME" |
importAutoCreateValues | N | "1" significa que os valores desse atributo podem ser criados por meio de importação. "0" (ou não especificado) significa que não podem. | 1 |
type | N | Indica se o atributo é um atributo de nível, conta ou dimensão. Obrigatório para criar novos atributos que ainda não existem no sistema. O tipo não pode ser alterado por uma operação de atualização. | account |
listDimensionName | N | Indica se a dimensão é uma dimensão de lista simples. Aplicável somente quando o tipo de atributo = dimensão. listDimensionName não pode ser alterado por uma operação de atualização. | cor |
keepSorted | N | "1" indica que os valores deste atributo são sempre classificados em ordem alfabética. "0" (ou não especificado) significa que os valores de atributo são classificados com base em sua posição na carga da solicitação. O valor por padrão é "0" somente na operação de criação quando nenhum valor é fornecido. Se o XML contém o valor pai e pelo menos um irmão de um valor de atributo hierárquico não listado, o valor não listado é movido para o fim dos irmãos listados durante a atualização (ao reordenar os filhos do pai, todos os irmãos listados vêm primeiro, em ordem em que são especificados no XML. Todos os irmãos não listados vêm por último, na ordem em que já estão no sistema). O método leaveSorted se aplica aos filhos de cada valor de atributo pai. Quando a opção Manter classificado está habilitada, quaisquer alterações nos componentes de um nome de exibição podem alterar a ordem de classificação dos elementos. | 1 |
shortName
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | O nome curto do atributo. O tamanho máximo em caracteres é 64.
Disponível somente quando Habilitar nome de exibição está ATIVADO para a instância. | Ativos |
descrição
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | A descrição do atributo. O tamanho máximo em caracteres é 2048.
Valor por padrão: vazio Essa propriedade só fica disponível quando a opção Habilitar nome de exibição está ATIVADA para a instância. | Ativos |
Conteúdo do elemento
| |||
Um ou mais elementos attributeValue. | |||
attributeValue element
| |||
Nome da etiqueta
| attributeValue | ||
Descrição
| Especifica os valores de atributo a serem criados ou atualizados. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
ID | N | Identifica o valor do atributo. Se deixado em branco, indica que um novo valor de atributo está sendo criado pela solicitação. | 24 |
código
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | O código exclusivo do valor do atributo.
| Sim |
nome
Atualizado na API v30 | S | O nome do valor do atributo, como aparece em planilhas e relatórios. Quando Habilitar nome de exibição está ATIVADO para uma instância com API v30 ou superior, o nome permite valores duplicados. Quando Habilitar nome de exibição está DESATIVADO para uma instância, o código não fica disponível e o nome deve ser exclusivo. Nomes de valores de atributos inválidos: nomes que terminam com (+) ou (-) | Sim |
descrição | N | A descrição textual do valor do atributo. Valor por padrão: vazio O valor por padrão só é usado na operação de criação quando nenhum valor é fornecido. | |
Conteúdo do elemento
| |||
Pode conter outro attributeValue. | |||
Formato da resposta
<?xml version="1.0" encoding="UTF-8"?> <response success="true"> <messages> <message type="INFO">Attributes were saved successfully.</message> </messages> <output> <attributes> <attribute id="13" name="AP Eligible" type="account"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9" name="Corporate Discount" type="level"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> <attributeValue id="57" name="Not Available" /> <attributeValue id="55" name="TBD" /> </attribute> <attribute id="10" name="Tax Code" type="level"> <attributeValue id="146" name="TT-PYT" /> <attributeValue id="145" name="TT-TRE" /> </attribute> <attribute id="16" name="Industry" type="dimension" listDimensionName="Education"> <attributeValue id="335" name="Apparel"> <attributeValue id="354" name="Mens Apparel" /> <attributeValue id="355" name="Shoes" /> <attributeValue id="356" name="Womens Apparel" /> </attributeValue> </attribute> </attributes> </output> </response>
elemento de saída
| |
Nome da etiqueta
| saída |
Atributos do elemento
| |
(nenhum) | |
Conteúdo do elemento
| |
Um único elemento de atributos obrigatórios. Esse invólucro de saída é padrão em todas as respostas de API e inclui a saída válida de qualquer chamada de API bem-sucedida. | |
elemento de atributos
| |||
Nome da etiqueta
| atributos | ||
Descrição
| Contêiner para zero ou mais elementos de atributo. As etiquetas são ordenadas com base na solicitação de entrada. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
proceedWithWarnings | N | O valor de prosseguiWithWarnings fornecido na solicitação de API. | 1 |
retainExistingOrder | N | updateAttributes=0 atualiza a ordem de classificação com base no conteúdo da carga XML. updateAttributes=1 retém a ordem de classificação existente. | 1 |
displayNameEnabled
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | displayNameEnabled = 1 indica que updateAttributes deve respeitar as propriedades de nome de exibição de code , displayNameType e description quando Habilitar nome de exibição está ATIVADO para a instância.displayNameEnabled = 0 indica que a updateAttribues API deve continuar seguindo o contrato de API anterior a 2021.42, mesmo quando a opção Habilitar nome de exibição está ATIVADA para a instância. A API updateAttribues ignora as propriedades de nome de exibição code , displayNameType e description .O suporte para displayNameEnabled começou em 2021.42. O valor por padrão para displayNameEnabled é "0". | 1 |
Conteúdo do elemento
| |||
Um ou mais elementos de atributo. | |||
elemento atributo
| |||||
Nome da etiqueta | atributo | ||||
Descrição
| Representa um único atributo que está sendo retornado em resposta a uma chamada à API updateAttributes. | ||||
Atributos do elemento
| |||||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
| ||
ID | S | O número da ID do sistema interno para o atributo. | 16 | ||
nome | S | O nome do atributo, como aparece em relatórios e planilhas. | Ativos atuais | ||
código
Disponível na API v39+. | S | O código do atributo. | Ativos atuais | ||
shortName | O nome curto do atributo. O tamanho máximo em caracteres é 2048. | Ativos | |||
displayNameType
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | Controla a exibição de valores de atributo. Os valores possíveis são NAME, CODE, NAME_CODE ou CODE_NAME.
O valor por padrão é NOME quando deixado em branco ou não fornecido. Essa propriedade só fica disponível quando a opção Habilitar nome de exibição está ATIVADA para a instância. | CODE_NAME | ||
importAutoCreateValues | N | "1" significa que os valores desse atributo podem ser criados por meio de importação. "0" (ou não especificado) significa que não podem. | 1 | ||
type | S | O tipo do atributo. Será "conta" se o atributo for para uma conta, "nível" se o atributo for para um nível ou "dimensão" se o atributo for para uma dimensão. | account | ||
listDimensionName | N | O nome da dimensão de lista se o atributo for do tipo "dimensão". | Formação | ||
descrição | N | A descrição textual do atributo, se houver, conforme inserida em Administração de atributos | Total de ativos atuais | ||
keepSorted | S | "1" indica que os valores deste atributo são sempre classificados em ordem alfabética. "0" (ou não especificado) significa que os valores de atributo são classificados com base em sua posição na carga da solicitação. Se o XML contém o valor pai e pelo menos um irmão de um valor de atributo hierárquico não listado, o valor não listado é movido para o fim dos irmãos listados durante a atualização (ao reordenar os filhos do pai, todos os irmãos listados vêm primeiro, em ordem em que são especificados no XML. Todos os irmãos não listados vêm por último, na ordem em que já estão no sistema). O método leaveSorted se aplica aos filhos de cada valor de atributo pai. | 1 | ||
status | S | O status do valor de atributo após a atualização. Para aviso e erro, o elemento de mensagem contém o conteúdo da mensagem. O status atualizado não retorna nenhum conteúdo da mensagem.
| Atualizado | ||
mensagem | N | A mensagem de erro para a entrada de atributo. | O atributo Setor está duplicado na carga ou já existe no sistema com a ID 8 | ||
Conteúdo do elemento
| |||||
Zero ou mais elementos attributeValue opcionais. Cada elemento attributeValue incluído representa um "valor de atributo raiz" no atributo, um valor que não tem valor pai. | |||||
attributeValue element
| |||
Nome da etiqueta
| attributeValue | ||
Descrição
| Representa um valor de membro único de um atributo que está sendo retornado em resposta a uma chamada à API updateAttributes. | ||
Atributos do elemento
| |||
Nome do atributo
| Obrigatório?
| Valor
| Exemplo
|
ID | S | O número de ID do sistema interno para esse valor de membro do atributo. | 34 |
código
Disponível somente na API v30+ para instâncias que habilitam o nome de exibição. | N | O código exclusivo do valor do atributo. | Disponível |
nome | S | O rótulo do valor de membro do atributo conforme exibido na página de administração de atributos. | Disponível |
shortName | N | O nome curto do valor de atributo. | Avl |
descrição | N | A descrição do valor do atributo. Valor por padrão: vazio O valor por padrão só é usado na operação de criação quando nenhum valor é fornecido. | |
propogateToDescendants | N | Indica se as alterações são propagadas para os filhos deste nível. 0 para não, 1 para sim. | 0 |
status | S | O status do atributo após a atualização. Para aviso e erro, o elemento de mensagem contém o conteúdo da mensagem. O status atualizado não retorna nenhum conteúdo da mensagem.
| atualizado |
mensagem | N | A mensagem de erro para uma entrada attributeValue inválida. | |
Conteúdo do elemento
| |||
Zero ou mais elementos attributeValue opcionais. Cada elemento attributeValue incluído representa um "valor de atributo filho" desse valor de atributo, cujos membros são consolidados implícitamente nesse valor. | |||