> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Importar atividades para o Maintain

> Aprenda como importar atividades usando a interface do usuário (modo APM), Cognite Toolkit ou Transformações.

O Maintain suporta três métodos para importar atividades:

* **Upload de CSV**: Importar atividades usando a interface do usuário (apenas modo APM).
* **Cognite Toolkit**: Ingerir atividades usando [Cognite Toolkit](/cdf/deploy/cdf_toolkit/) modelagem de dados (modos APM e IDM/CDM).
* **Transformações**: Converter dados de tabelas RAW ou outras fontes usando [CDF Transformations](/cdf/integration/) (modos APM e IDM/CDM).

## Importar via upload de CSV (modo APM)

<Info>
  **Disponibilidade do modo**: Apenas modo APM. O modo IDM/CDM não suporta importação de CSV na interface do usuário.
</Info>

Atividades importadas via CSV podem ser visualizadas e modificadas como atividades criadas no Maintain.

<Steps>
  <Step title="Baixe o modelo de arquivo CSV">
    O arquivo CSV importado precisa estar em conformidade com o seu modelo específico do projeto. Para baixar **maintain-import-template.csv**:

    1. Navegue até **Atividades** e selecione **Adicionar atividade**.
    2. Selecione **Importar atividades**.
    3. Selecione **Baixar modelo**.
  </Step>

  <Step title="Preencha o modelo de arquivo CSV">
    O modelo CSV conterá apenas uma única linha de valores representando os possíveis valores que você pode fornecer para uma atividade importada. Esta linha é chamada de linha de cabeçalho e não deve ser removida ao preencher o modelo.

    <Tip>
      Embora a linha de cabeçalho **row** não deva ser removida, você pode remover valores específicos do cabeçalho ou alterar a ordem dos valores. Por exemplo, se um determinado campo não for relevante para importar em um cenário específico, você pode removê-lo do cabeçalho e das linhas subsequentes. Isso resultará no campo sendo deixado em branco em todas as atividades importadas.
    </Tip>

    Para importar uma única atividade, adicione uma nova linha ao modelo e insira os valores apropriados separados por vírgulas. Cada valor na nova linha deve conter o valor que você deseja preencher na respectiva linha de cabeçalho que foi fornecida no modelo.

    Por exemplo, se seu modelo contiver a seguinte linha de cabeçalho: `title,status,department`, crie um arquivo CSV com uma linha adicional:

    ```
    title,status,department 
    Montar andaimes,Concluído,Rigging
    ```

    Você criará uma atividade com o título "Montar andaimes", status "Concluído" e departamento "Rigging" quando importado.

    <a id="format-date-fields" />

    ### Formatar campos de data

    Alguns campos de atividade em **Maintain** representam datas e devem ter um formato específico para serem importados corretamente. Os campos de data podem ser identificados no modelo CSV por um valor de cabeçalho especial na forma `startTime (DD/MM/YYYY)`. Neste exemplo, `startTime` é o nome do campo, enquanto `DD/MM/YYYY` é o formato de data que precisa ser usado nas linhas subsequentes do arquivo CSV.

    Por exemplo, importar o seguinte arquivo resultará na atividade sendo criada com `startTime` definido para 10 de dezembro de 2023.

    ```
    title,startTime (DD/MM/YYYY) 
    Montar andaimes,10/12/2023 
    ```

    <a id="format-boolean-fields" />

    ### Formatar campos booleanos

    Alguns campos de atividade em **Maintain** representam valores booleanos, como `true` ou `false`. Os campos booleanos podem ser identificados no modelo CSV por um valor de cabeçalho especial na forma `isActive (true/false)`. Esses campos só têm dois valores válidos, `true` ou `false`.

    Por exemplo, importar o seguinte arquivo resultará na atividade sendo criada com `isActive` definido como `false`.

    ```
    título, estáAtivo (verdadeiro/falso) 
    Montar andaimes, falso 
    ```

    <a id="format-values-containing-commas" />

    ### Formatar valores que contêm vírgulas

    Devido ao formato CSV separar valores usando vírgulas, tenha cuidado quando um campo de atividade também precisar conter uma vírgula. **Maintain** processos de arquivos CSV de acordo com o [padrão RFC 4180](https://www.rfc-editor.org/rfc/rfc4180), que exige que valores contendo vírgulas sejam envoltos em aspas duplas.

    Por exemplo, importar o seguinte arquivo resultará na atividade sendo criada com `cidade` definida como `Boston, MA`.

    ```
    title,city 
    Erect scaffolding,"Boston, MA" 
    ```

    <a id="unset-values" />

    ### Valores não definidos

    Você pode deixar o campo em branco em campos de atividade não obrigatórios para representar valores ausentes ou irrelevantes para a atividade específica.

    Por exemplo, importar o seguinte arquivo resultará na atividade sendo criada com `estado` definida como `Nova York`, mas não terá valor no campo `cidade`.

    ```
    título,cidade,estado 
    Montar andaimes,Nova York 
    ```

    <a id="connect-an-activity-to-an-asset" />

    ### Conectar uma atividade a um ativo

    **Maintain** suporta vincular atividades a ativos CDF, que são usados para contextualizar a atividade em modelos 3D, documentos, PSN e mais. Para **Maintain** criar o link apropriado a um ativo no CDF, você deve fornecer o ID externo do ativo CDF no modelo de importação.

    Se você tiver contextualização de ativos em seu projeto, haverá um campo especial `assetExternalId` no modelo que você precisa preencher com o ID externo do ativo da atividade.

    Por exemplo, ao importar o seguinte arquivo e assumindo que um ativo CDF existe com ID externo `NY_BUILDING_23`, a atividade será contextualizada a este ativo quando ingerida no Maintain.

    ```
    título,assetExternalId 
    Montar andaimes,NY_BUILDING_23 
    ```

    Se o ID externo fornecido não for exportado, o usuário verá um erro durante a importação.

    <Tip>
      Os usuários finais podem não saber o ID externo do ativo ao qual a atividade está vinculada. Se for necessário fornecer aos usuários finais uma lista dos possíveis ativos e seus IDs externos, recomendamos recuperar esses dados usando a [API de ativos](/api-reference/concepts/20230101/assets) do CDF ou outros extratores de dados.
    </Tip>
  </Step>

  <Step title="Importe um arquivo CSV preenchido">
    Uma vez que você tenha um modelo CSV preenchido, pode importá-lo para **Maintain**:

    1. Navegue até **Atividades** > **Adicionar atividade**.
    2. Selecione **Importar atividades**.
    3. Selecione o campo **Clique para selecionar o arquivo CSV para importar**.
    4. Selecione e faça o upload do arquivo CSV preenchido do seu computador.
    5. Verifique se você importou o arquivo conferindo a seção **Inspetor de Arquivos**. Uma mensagem verde deve mostrar o número de linhas a serem importadas e se você tem avisos ou erros.
    6. Se não houver erros, selecione **Importar** para iniciar o processo de importação.
    7. Quando a importação for bem-sucedida, você verá uma mensagem de sucesso verde com o botão **Mostrar atividades**.
    8. Opcional: Selecione **Mostrar atividades** para navegar até as atividades importadas e verificar se estão corretas de acordo com o arquivo CSV.
  </Step>
</Steps>

## Importar via Cognite Toolkit

<Info>
  **Disponibilidade do modo**: Modos APM e IDM/CDM. Esta é a abordagem recomendada para a ingestão programática de atividades.
</Info>

Use o [Cognite Toolkit](/cdf/deploy/cdf_toolkit/) para ingerir atividades através das capacidades de modelagem de dados do CDF. Este método funciona para ambos os modos de implantação e fornece controle de versão e implantações reproduzíveis.

### Pré-requisitos

Antes de importar atividades via Cognite Toolkit, certifique-se de que você tem:

* Uma visualização de atividade personalizada configurada no seu espaço de modelo de dados (ou use a visualização padrão `Ordem de Maintain Cognite` do `cdf_idm`)
* A visualização de atividade mapeada na sua configuração de Maintain sob `mapeamentosDeVisualização`
* Acesso ao [Cognite Toolkit](/cdf/deploy/cdf_toolkit/)

### Configure o mapeamento da visualização de atividade

Na sua configuração de Maintain, verifique se a seção `mapeamentosDeVisualização` aponta para sua visualização de atividade:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
"viewMappings": { 
    "activity": { 
        "type": "view", 
        "space": "cdf_idm", 
        "version": "v1", 
        "externalId": "CogniteMaintenanceOrder" 
    } 
} 
```

Se você criou uma visualização de atividade personalizada (por exemplo, `APM_Activity` ou `ExtendedActivity`), atualize o mapeamento para apontar para sua visualização personalizada:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
"viewMappings": { 
    "activity": { 
        "type": "view", 
        "space": "maintain_schema_extention", 
        "version": "v1", 
        "externalId": "APM\_Activity" 
   }
} 
```

Saiba mais sobre [extensão de modelos de dados](/cdf/maintain/guides/config#extend-data-models) e [configuração de mapeamentos de visualização](/cdf/maintain/guides/config#view-mappings).

### Ingestão de atividades com o Cognite Toolkit

Use o [Cognite Toolkit](/cdf/deploy/cdf_toolkit/) como a abordagem recomendada para a ingestão de atividades no modo IDM.

<Steps>
  <Step title="Crie a estrutura de dados da atividade">
    Se você ainda não o fez, crie arquivos YAML de Container, View e Node para suas atividades. Siga a estrutura padrão de modelagem de dados:

    * `APM_Activity.Container.yaml` - Define o esquema do container
    * `APM_Activity.View.yaml` - Define as propriedades e relacionamentos da visualização
    * `apmActivities.Node.yaml` - Contém suas instâncias de atividade
      Consulte a [Cognite Toolkit documentação](/cdf/deploy/cdf_toolkit/) para exemplos e modelos detalhados.
  </Step>

  <Step title="Configure os mapeamentos de campos">
    Certifique-se de que seus nós de atividade incluam os campos obrigatórios para Maintain:

    | Campo             | Descrição                                                                | Obrigatório |
    | ----------------- | ------------------------------------------------------------------------ | ----------- |
    | `externalId`      | Identificador único para a atividade                                     | Sim         |
    | `título`          | Título da atividade                                                      | Sim         |
    | `status`          | Status da atividade (por exemplo, "Aberto", "Em Progresso", "Concluído") | Recomendado |
    | `startTime`       | Data/hora de início                                                      | Recomendado |
    | `endTime`         | Data/hora de término                                                     | Recomendado |
    | `rootLocation`    | Identificador do local raiz                                              | Recomendado |
    | `assetExternalId` | ID externo do ativo vinculado                                            | Opcional    |
    | `mainAsset`       | Relação direta com o ativo                                               | Opcional    |

    <Tip>
      Inclua campos adicionais com base nas suas configurações de [Configuração de Campo](/cdf/maintain/guides/config#field-configuration) em Maintain.
    </Tip>
  </Step>

  <Step title="Implante as atividades">
    Implemente seus dados de atividade usando o Cognite Toolkit:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --env dev 
    ```

    Use a flag `--drop-data` se precisar substituir atividades existentes:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --env dev --drop-data
    ```

    Saiba mais sobre as [flags de implantação do Cognite Toolkit](/cdf/maintain/guides/config#critical-deployment-flags).
  </Step>

  <Step title="Verifique em Maintain">
    1. Faça login em [Maintain](https://maintain.cogniteapp.com).
    2. Navegue até **Atividades**.
    3. Verifique se suas atividades importadas aparecem com os dados corretos.
  </Step>
</Steps>

### Ingestão de atividades com Transformações

<Info>
  **Disponibilidade do modo**: Modos APM e IDM/CDM. Esta é a abordagem recomendada para dados em massa.
</Info>

Alternativamente, você pode usar [Transformações CDF](/cdf/integration/) para converter dados de tabelas RAW ou outras fontes em nós de atividade.

### Solução de problemas

Se você encontrar problemas com atividades após a ingestão, consulte a tabela para causas e soluções.

| Problema                  | Solução                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| Atividades não visíveis   | Verifique se a configuração de `viewMappings` aponta para o espaço, visualização e versão corretos |
| Campos ausentes           | Verifique se sua Configuração de Campo inclui todos os campos que você está ingerindo              |
| Links de ativos quebrados | Certifique-se de que as relações `assetExternalId` ou `mainAsset` apontam para ativos existentes   |
| Localização raiz errada   | Verifique se `rootLocation` corresponde à sua configuração de localização                          |