Centrum wsparcia Workiva

Tło

Chains współdziała z różnymi systemami innych firm, a także z platformą Workiva, wykorzystując REST API systemu, z którym się integruje. Wiele odpowiedzi REST API jest w formacie JSON, w tym różne interfejsy API Workiva. Chociaż odpowiedź JSON może być dobrze udokumentowana i spójnie ustrukturyzowana, trudno jest pracować z danymi w tym formacie. Polecenie Array to CSV w konektorze JSON to przydatny sposób na konwersję ładunku JSON do formatu tabelarycznego (wiersze i kolumny) do użytku na platformie Workiva. 

W tym artykule zbadamy, jak korzystać z możliwości filtrowania tego polecenia, aby zwracać tylko te wyniki z ładunku JSON, które są potrzebne. Może to być konieczne, ponieważ odpowiedź REST API często zawiera więcej informacji niż jest to potrzebne, ponieważ ładunek jest generalnie określany przez programistów, a użytkownicy końcowi punktu końcowego często nie mają możliwości ograniczenia zakresu zwracanych danych. 

Przykładowo, polecenie List Files Command konektora Workiva wykorzystuje punkt końcowy Retrieve a List of Files z interfejsu API Workiva Wdata, aby zwrócić listę wszystkich plików powiązanych z tabelą Wdata. Odpowiedź JSON dla tego punktu końcowego zawiera następujące informacje:

 [ 
 { 
 "created": "2024-01-24T12:01:53.000Z", 
 "id": "89b34ac927fe499abf944571ded77983", 
 "metadata": { 
 "column1": {}, 
 "column2": {}
 }, 
 "name": "executions_2024-01.csv", 
 "numRecords": 108808, 
 "originalFileSize": 26226080, 
 "status": "IMPORTED", 
 "tableId": "bafe350ebff74a2dbc11262245483dee", 
 "updated": "2024-01-24T12:02:03.000Z", 
 "userId": "HzU1OTQwMTMxODMzMTE4NzI", 
 "version": 1 
 },
 { 
 "created": "2023-12-18T15:06:56.000Z", 
 "id": "62f3d0b79b724776a4fae8bf25f711f1", 
 "metadata": { 
 "column1": {}, 
 "column2": {}
 }, 
 "name": "executions_2023-12.csv", 
 "numRecords": 101789, 
 "originalFileSize": 24226080, 
 "status": "IMPORTED", 
 "tableId": "bafe350ebff74a2dbc11262245483dee", 
 "updated": "2023-12-18T15:06:56.000Z", 
 "userId": "HzU1OTQwMTMxODMzMTE4NzI", 
 "version": 1 
 }
]

Polecenie Array to CSV pozwala nam wybrać tylko te pola, które możemy pobrać z odpowiedzi JSON. Na przykład, możemy wybrać pola id, name i status, określając je w sekcji wprowadzania kolumn polecenia. Polecenie wyodrębni każdy identyfikator pliku, nazwę i status z odpowiedzi JSON i utworzy wiersz dla każdego pliku w odpowiedzi JSON.  

Kontynuując powyższy przykład z plikami list, częstym przypadkiem użycia na platformie Workiva jest potrzeba aktualizacji danych (pliku) w tabeli Wdata. Aby zaimportować zaktualizowany zestaw danych (plik), istniejący zestaw danych musi zostać usunięty z tabeli, ponieważ Wdata nie zezwala na wiele plików o tej samej nazwie. Aby usunąć istniejący plik, należy pobrać jego identyfikator i status (Staged lub Imported). 

Jednym z podejść do pobierania tych informacji jest konwersja ładunku List Files JSON do formatu tabelarycznego przy użyciu polecenia Array to CSV. Następnie użyj polecenia Tabular Transformation Smart Filter Rows, aby wyodrębnić pojedynczy wiersz z informacjami o pliku. Następnie użyj polecenia Tabular Transformation Extract Value, aby pobrać ID pliku i status. Na potrzeby tego artykułu nazwiemy to podejściem Legacy.   

Korzystanie z filtrów

Wejście Filter umożliwia filtrowanie odpowiedzi JSON nie tylko pod względem pól (kolumn) do wyboru, ale także elementów (wierszy), które zostaną pobrane z ładunku JSON. Jest to potężny mechanizm umożliwiający wybór konkretnych potrzebnych danych, co poprawia wydajność procesu integracji. Filtr pozwala na użycie jednego lub więcej elementów w ładunku JSON w celu ograniczenia liczby pobieranych elementów (wierszy). 

Kryterium filtra składa się z 3 komponentów - ścieżki elementu, wartości porównania i operatora. Kryteria muszą mieć wartość true lub false. Gdy kryteria filtrowania zwrócą wartość true, rekord zostanie wyodrębniony z ładunku JSON zgodnie z definicją Command Columns i utworzony jako wiersz w wynikowym pliku CSV. Na przykład:

• Czy status pliku jest równy Staged?

W tym przykładzie status pliku to ścieżka elementu, equal to operator, a Staged to wartość porównania. Każdy rekord w ładunku JSON, w którym status pliku to Staged, tworzy wiersz w CSV zawierający definicję kolumn w konfiguracji poleceń. W tym przykładzie są to ID, nazwa i status.

Ścieżka elementu

Aby określić filtr, ścieżka do elementu musi być znana. Na przykład w odpowiedzi List Files ścieżka do elementu Status to:

@.status

Wartość powiązana z elementem jest pobierana podczas wykonywania polecenia. W powyższym przykładzie ładunku byłaby to wartość IMPORTED dla elementu status . 

Uwaga: Ścieżka elementu musi rozpoczynać się od symbolu (@).

Wartość porównawcza

Wartość porównania to wartość, z którą porównywana jest wartość ścieżki elementu. Wartość porównania może być wartością statyczną zdefiniowaną w konfiguracji polecenia lub może wykorzystywać zmienną lub wartość wyjściową, która jest określana podczas wykonywania.  

Operator

Operator określa typ oceny, która zostanie przeprowadzona w celu filtrowania danych. 

Uwaga: Wymagana jest spacja między ścieżką elementu a operatorem , a także między operatorem a wartością porównania.

Obsługiwani operatorzy

Ważne jest, aby wziąć pod uwagę typ wartości, które istnieją dla ścieżki elementu podczas określania operatora. Na przykład użycie operatora greater than (>) potencjalnie spowodowałoby wyświetlenie pustego wyniku podczas oceny elementu zawierającego wartości tekstowe, ponieważ ocena liczbowa wartości tekstowej jest nielogiczna.

Składnia filtrów i przykładowe filtry

Wszystkie filtry muszą zaczynać się od znaku zapytania (?) i być zawarte w nawiasach.  

Pojedyncze kryteria

Pojedyncze kryterium filtrowania wykorzystuje następującą składnię:

?(Element_Path Operator Comparison_Value)

?(@.name == "executions_2023-12.csv")

Ten filtr zwraca wszystkie rekordy, w których element name jest równy executions_2023-12.csv.

Wiele kryteriów

Filtr wielu kryteriów wykorzystuje następującą składnię:

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

?(@.name == "executions_2023-12.csv" && @.status == "IMPORTED")

Ten filtr zwraca wszystkie rekordy, w których element name jest równy executions_2023-12.csv, a element status jest równy IMPORTED.

Przykładowa konfiguracja poleceń

W tym przykładzie wejście Filter jest skonfigurowane do oceny elementu name w ładunku JSON. Filtr używa zmiennych dla roku i miesiąca, które w tym przykładzie są wartościami wejściowymi środowiska wykonawczego. Umożliwia to filtrowi dynamiczne uwzględnianie roku i miesiąca określonego podczas wykonywania łańcucha.  

Wartość filtrów

Filtry umożliwiają pobieranie tylko wymaganych wierszy z odpowiedzi JSON. Może to zmniejszyć rozmiar pliku wyjściowego generowanego przez polecenie, co może poprawić wydajność łańcucha. 

Dodatkowo, podczas próby wyodrębnienia pojedynczego wiersza z odpowiedzi JSON, Dynamic Outputs może być użyty do wyodrębnienia tych konkretnych wartości z przefiltrowanego ładunku i udostępnienia ich do wykorzystania w kolejnych węzłach łańcucha. 

Poniżej przedstawiono przykładowe definicje wyjścia dynamicznego.

Wynikowy łańcuch jest bardziej usprawniony dzięki pojedynczemu węzłowi (Array to CSV) wykonującemu operacje czterech węzłów wymagane w starszym podejściu. Ten usprawniony łańcuch działa również bardziej wydajnie, ponieważ wykonywana jest mniejsza liczba poleceń, a wynikowe dane wyjściowe są mniejsze.